项目简介

耶温博客（SimpleBlog）是一个现代化、极简风格的个人博客系统，基于 Vue 3 + TypeScript + Vite 构建。

采用静态站点生成（SSG）方案，提供极佳的性能和 SEO 优化。设计理念是”简约而不简单”，在保持界面清爽的同时，提供完整的功能体验。

核心特性

📝 内容管理

  • Markdown 支持 - 使用 Markdown 格式编写文章，支持 front-matter 元数据
  • 智能路由 - 自动生成文章列表和详情页路由
  • 分类标签 - 支持文章分类和标签系统
  • 文章目录 - 自动生成目录树，支持快速导航

🔍 搜索功能

  • 全文搜索 - 搜索文章标题、标签和简介
  • 快捷键支持 - Cmd/Ctrl + K 或 Q 快速打开搜索
  • 多关键词搜索 - 空格分隔多个关键词
  • 实时结果 - 300ms 防抖优化，流畅的搜索体验

💬 评论系统

  • Giscus 集成 - 基于 GitHub Discussions 的轻量级评论系统
  • 多主题支持 - 支持浅色、深色等多种主题
  • Markdown 支持 - 评论支持 Markdown 语法和代码高亮

🎨 视觉效果

  • 水墨涟漪 - 首页水墨风格背景动画
  • 雪花飘落 - 冬日主题雪花效果，响应式数量适配
  • 毛玻璃设计 - macOS 风格 Dock 导航菜单，透明液态玻璃效果

📊 数据展示

  • Git 活动图 - 类似 GitHub 的贡献度热力图
  • 最新文章 - 首页底部显示最新文章列表

⚡ PWA 支持

  • 离线访问 - 支持 Service Worker 缓存
  • 添加到主屏幕 - 可安装为桌面应用
  • 自动更新 - Service Worker 自动更新策略

🚀 性能优化

  • 静态站点生成 - 使用 vite-ssg 预渲染所有页面
  • 代码高亮 - 基于 Shiki 的语法高亮，支持 47+ 种编程语言
  • 按需加载 - 路由和组件懒加载，减少首屏体积
  • XSS 防护 - 使用 DOMPurify 净化 HTML内容
  • 路径验证 - 严格的 slug 验证，防止路径遍历攻击

技术栈

核心框架

  • Vue 3.5 - 渐进式 JavaScript 框架
  • TypeScript 5.6 - 类型安全
  • Vite 6.0 - 构建工具
  • Vue Router 4.5 - 路由管理器

核心功能

  • markdown-it 14.1 - Markdown 解析器
  • Shiki 1.24 - 代码高亮
  • DOMPurify 3.2 - XSS 防护
  • Giscus - 评论系统

其他

  • vite-ssg - 静态站点生成器
  • vite-plugin-pwa - PWA 支持
  • Vercel Analytics - 网站分析
  • ESLint - 代码检查
  • Prettier - 代码格式化

快速开始

环境要求

  • Node.js >= 18.0.0
  • npm >= 9.0.0

安装依赖

npm install

开发模式

npm run dev

访问 http://localhost:3000

构建生产版本

npm run build

构建产物位于 dist/ 目录。

撰写文章

文件位置

在 docs/ 目录下创建 .md 文件：

docs/
├── 技术/
│   ├── Vue/
│   │   └── vue-composition-api.md
│   └── TypeScript/
│       └── ts-best-practices.md
└── 耶温/
    └── 关于本站.md

文章格式

---
id: a1b2c3d4
title: 文章标题
date: 2026-01-16
category: 分类/子分类
excerpt: 文章简介
author: 耶温
tags:
  - Vue
  - TypeScript
---

文章内容...

Front-matter 字段

字段必填说明
id是文章唯一标识（8位字母数字）
title是文章标题
date是发布日期（YYYY-MM-DD）
category否文章分类（可从路径推断）
excerpt否文章简介（用于搜索和列表）
author否作者名称
tags否文章标签

自动补全 Front-matter

开发模式下，保存新文章时会自动补全缺失字段：

  • ✅ title - 从文件名推断
  • ✅ date - 当前日期
  • ✅ category - 从目录路径推断
  • ✅ id - 随机生成 8 位 ID

运行以下命令手动生成文章 ID：

npm run ensure-ids

项目配置

站点信息

编辑 config/site.config.ts 修改站点配置：

export const SITE_CONFIG = {
  title: '耶温博客',
  description: '记录思考，分享知识',
  keywords: '耶温博客, 技术博客',
  author: '耶温',
  url: 'https://blog.yuwb.cn',
}

主题颜色

编辑 app/src/styles/variables.css 自定义主题：

:root {
  --color-text: #3a3a3a;
  --color-bg: #ffffff;
  --color-accent: #1a1a1a;
}

可用脚本

命令说明
npm run dev启动开发服务器（端口 3000）
npm run build生产构建到 dist/ 目录
npm run preview预览生产构建
npm run prepare同步图片、获取 Git 活动、补全 ID、生成文章索引
npm run prepare:build同步图片、补全 ID、生成文章索引、生成 sitemap
npm run sync-images同步 images/ 到 app/public/images/
npm run fetch-git生成 Git 活动数据
npm run ensure-ids为缺失 ID 的文章生成唯一标识
npm run generate-article-index生成文章索引
npm run generate-sitemap生成 sitemap
npm run format格式化代码
npm run lint代码检查

常见问题

Q: 如何修改网站标题和描述？

A: 编辑 config/site.config.ts 中的 SITE_CONFIG。

Q: 文章 ID 是如何生成的？

A: 开发模式下保存新文章时会自动生成 8 位随机 ID（小写字母+数字），也可运行 npm run ensure-ids 手动生成。

Q: 如何禁用首页动画？

A: 编辑 app/src/pages/HomePage.vue，注释掉 <InkBackground /> 和 <SnowfallEffect /> 组件。

Q: 支持哪些编程语言的代码高亮？

A: 支持 JavaScript、TypeScript、Bash、Python、Java、Go、Rust、HTML、CSS、Markdown、JSON、YAML、SQL、Dockerfile 等 47+ 种语言。

Q: 如何自定义代码高亮主题？

A: 编辑 app/src/utils/markdown.ts 中的 highlighter 初始化配置，修改 theme 参数。

Q: 如何配置评论系统？

A: 编辑 config/giscus.config.ts，填入你的 GitHub 仓库信息和 Giscus 配置参数。

Q: 如何部署到 Vercel？

A: Fork 项目后在 Vercel 导入仓库即可，Vercel 会自动检测 Vite 配置并构建。

开源协议

本项目采用 MIT License 开源协议。

联系方式

浏览器支持

  • Chrome（推荐）
  • Firefox
  • Safari
  • Edge

致谢

感谢以下开源项目和工具：

  • Vue.js - 渐进式 JavaScript 框架
  • Vite - 下一代前端构建工具
  • Shiki - 代码语法高亮
  • Giscus - 评论系统
  • Antfu - 开源项目和工具