更新日志

本页面记录了 VitePress 学习指南的重要更新和变更。

2026年04月10日

📝 生态系统模块深度扩充

大幅扩充生态系统模块的 7 篇集成方案文档，从概览级内容升级为完整实操指南：

文件	原大小	扩充后	核心新增内容
`ecosystem/comments.md`	~2.7 KB	~15 KB	Giscus/Waline/Twikoo/Artalk 完整集成代码、迁移指南
`ecosystem/search.md`	~4.3 KB	~14 KB	Pagefind/MeiliSearch 完整配置、搜索方案迁移指南
`ecosystem/analytics.md`	~3.7 KB	~13 KB	SPA 追踪修复、Cookie 同意、事件追踪、多方案组合
`ecosystem/deployment.md`	~3.6 KB	~13 KB	Vercel/Netlify/CF Pages 完整配置、Docker 部署、检查清单
`ecosystem/cms.md`	~3.0 KB	~14 KB	Strapi/Notion/Contentful/Sanity/TinaCMS 数据加载器代码
`ecosystem/themes.md`	~5.1 KB	~11 KB	完整布局插槽表、主题迁移指南、主题发布流程
`ecosystem/plugins.md`	~5.2 KB	~11 KB	代码复制/PWA/NProgress 配置、插件冲突排查

👥 社区板块内容扩充

文件	变更	说明
`community/faq.md`	8 → 30+ 问题	从 8 个基础问题扩充至 30+ 个常见问题，覆盖安装配置、构建部署、样式主题、组件开发、SEO、性能等
`community/events.md`	~2.6 KB → ~5 KB	新增更多往期活动记录、分享主题建议、活动形式说明
新增 `community/learning-resources.md`	—	视频教程、精选文章、社区项目、工具资源汇总

🔧 配置更新

侧边栏 community/ 模块新增"学习资源"入口（带"新"标签）
导航栏"资源"菜单新增"学习资源"链接（带"新"标签）

2026年04月08日

🧹 内容清理与架构优化

清理重定向页面：

删除 advanced/api-config.md（已迁移至 /reference/site-config）
删除 advanced/api-runtime.md（已迁移至 /reference/runtime-api）
移除侧边栏 /advanced/ 下"API 参考（已迁移）"分组
更新 12 处旧链接引用（文档正文、frontmatter prev/next、Vue 组件数据）

修复 frontmatter：

basics/assets.md 补充 updated 和 difficulty 字段
修复 advanced/deployment.md frontmatter 损坏（wei--- → ---）

优化内容检查脚本：

scripts/content-freshness.mjs 跳过代码块和 frontmatter 区域，避免误报
"已废弃" 仅匹配提示框语境，"即将废弃" 跳过表格行
移除 deprecated: 关键词（代码属性名，非待办事项）
扫描结果：待办事项误报从 4 项降为 0

📊 Mermaid 图表深入教程

新增 /docs/basics/mermaid.md：

图表类型	用途
流程图	业务流程、决策逻辑
序列图	交互时序、API 调用
甘特图	项目排期、里程碑
类图	数据模型、继承关系
饼图	占比分析、统计分布
状态图	状态流转、生命周期
ER 图	数据库设计、实体关系

还包含暗色主题适配、Vue 组件动态渲染、导出为 SVG 等进阶用法。

🔄 版本升级指南

新增 /docs/guide/migration-v2.md：

内容	说明
v1→v2 Breaking Changes	配置、主题、构建三维度变更清单
升级检查清单	30+ 检查项，分优先级
渐进式升级策略	逐模块迁移，降低风险
回滚方案	git 回退 + 配置备份

📦 生态系统扩充与去重叠

扩充内容：

ecosystem/plugins.md — 新增插件选择标准、按功能分类表、冲突排查、Markdown-it 插件开发示例
ecosystem/themes.md — 新增主题选择决策树、功能对比表、迁移注意事项

去重叠精简（ecosystem/ 定位为选型概览，advanced/ 定位为深度教程）：

文件	修改策略
`ecosystem/comments.md`	保留对比表+决策流程，删除完整组件代码，链接指向 advanced/
`ecosystem/search.md`	Algolia 精简为快速配置，保留本地搜索/FlexSearch/Pagefind 独有内容
`ecosystem/analytics.md`	保留对比表+快速配置，新增 Microsoft Clarity，链接指向 advanced/
`ecosystem/deployment.md`	保留对比表+快速部署步骤，链接指向 advanced/
`ecosystem/cms.md`	保留对比表+简介+数据流图，链接指向 advanced/
`community/faq.md`	精简为 10 个最高频问题，链接指向 best-practices/faq

2026年04月07日

📊 性能基准测试报告

新增详细的性能基准测试文档 /docs/best-practices/performance-benchmark.md：

测试维度	VitePress	VuePress	Docusaurus
构建时间 (200 页)	8.2s	15.6s	23.4s
开发启动	320ms	1.2s	2.1s
LCP	0.8s	1.2s	1.5s
资源体积	129 KB	211 KB	313 KB
Lighthouse	98 分	89 分	82 分

包含内容：

测试环境配置说明
构建/开发/运行时性能对比
不同网络条件测试
压力测试报告
本地自测指南

🏢 企业级案例研究

新增企业级案例研究文档 /docs/examples/enterprise-case-study.md：

案例	页面数	团队规模	月访问量
Vue.js 官方文档	500+	20+	500 万+
Element Plus	80+ 组件	50+	200 万+
企业知识库	2000+	5	5000 用户
VueUse	200+ 函数	10+	18K Stars

包含内容：

企业级需求分析框架
4 个深度案例解析
企业级最佳实践
选型决策建议

🔧 故障排查手册完善

更新 /docs/best-practices/error-handling.md：

新增 错误代码速查表（20+ 常见错误码）
新增 场景排查指南（构建失败、运行时错误、部署问题）
新增 诊断工具箱（日志分析、环境检查）

📦 迁移专题指南更新

更新 /docs/guide/migration-other.md：

新增 6 种工具迁移方案（VuePress、Docusaurus、Docsify、GitBook、Hexo、JSDoc）
新增预计迁移时间
新增迁移决策树

📚 模块索引页面扩充

文件	新增内容
`ecosystem/index.md`	工具选择指南、决策流程图
`reference/index.md`	API 速查表、配置模板
`recipes/index.md`	配方分类表、使用场景

🏷️ Tags 风格统一

制定标签命名规范并修复不一致：

修复项	原值	修复后
技术名词大小写	`vitepress`、`vue`	`VitePress`、`Vue`
中英文格式	`API文档`	`API 文档`

新增 tags.md 标签风格规范章节：

英文标签首字母大写规则
中文标签命名规范
中英文混合格式规则

📝 Frontmatter 元数据完善

文件	补充内容
`404.md`	添加 description
`tutorial/index.md`	补充完整 frontmatter

📄 项目说明文件更新

更新 README.md：

新增性能基准测试、企业级案例统计项
更新最佳实践列表
更新路线图已完成项（9 项）

📑 目录索引页面完善

为 5 个主要模块添加索引页面，提升导航体验：

文件	内容概要
`guide/index.md`	入门指南模块索引，包含快速开始、安装配置等
`basics/index.md`	基础功能模块索引，包含 Markdown、路由、导航等
`theme/index.md`	主题定制模块索引，包含自定义主题、布局插槽等
`advanced/index.md`	高级功能模块索引，包含国际化、数据加载、部署等
`best-practices/index.md`	最佳实践模块索引，包含性能优化、SEO、安全等

优化效果：

侧边栏导航支持模块首页跳转
模块内容概览一目了然
支持快速定位所需内容

👥 社区板块内容扩充

新增 3 个社区页面，完善社区生态：

文件	内容
`community/events.md`	社区活动、线上会议、线下聚会信息
`community/roadmap.md`	项目路线图、版本规划、功能展望
`community/contributing-guide.md`	贡献指南、开发流程、代码规范

🔧 Markdown 格式规范修复

批量修复不符合 VitePress 标准的 Markdown 格式：

表格格式修复

将非标准 ||---| 格式修正为 |---|，涉及 11 个文件：

目录	修复文件数
`community/`	1
`ecosystem/`	1
`tutorial/`	1
`reference/`	1
`examples/`	1
`guide/`	2
`advanced/`	1
`basics/`	1
`best-practices/`	2

代码块语言标识修复

为目录结构代码块添加 text 语言标识，涉及 6 个文件：

tutorial/first-site.md
tutorial/deploy.md
tutorial/custom-theme.md
tutorial/component-docs.md
tutorial/i18n.md
changelog.md

🔗 教程导航链接完善

为 11 个教程页面添加 prev/next 导航链接：

first-site → installation → navigation → theme-colors → 
custom-theme → custom-layout → component-docs → blog → 
comments → i18n → plugin-dev → deploy

⚙️ 配置文件更新

更新 config.mts 侧边栏配置：

新增社区板块导航项（活动、路线图、贡献指南）
优化侧边栏分组结构

2026年04月06日

📝 内容优化

重复文档清理

清理了 /advanced/ 目录下的重复 API 文档，简化为重定向页面：

文件	修改前	修改后
`advanced/api-config.md`	412 行完整内容	30 行重定向页面
`advanced/api-runtime.md`	382 行完整内容	31 行重定向页面

优化效果：

消除了与 /reference/ 目录下文档的内容重复
用户访问旧链接时会看到明确的迁移提示
使用 <VPLink> 组件提供美观的跳转卡片

🌐 生态系统模块完善

补全生态系统模块的集成方案文档，新增 5 篇完整文档：

文件	内容
`ecosystem/comments.md`	评论系统对比（Giscus、Waline、Twikoo）与集成指南
`ecosystem/search.md`	搜索服务方案（本地搜索、Algolia、DocSearch、FlexSearch）
`ecosystem/analytics.md`	数据统计方案（Google Analytics、百度统计、Umami、Plausible）
`ecosystem/deployment.md`	部署平台选择（Vercel、Netlify、GitHub Pages、Cloudflare、Railway、Zeabur）
`ecosystem/cms.md`	CMS 集成方案（Strapi、Notion、Contentful、Sanity、TinaCMS）

文档特点：

每篇文档包含完整的功能对比表格
提供详细的安装配置步骤
包含代码示例和最佳实践建议
支持快速选择和决策流程图

📐 示例页面完善

完善 4 个简略示例页面，补充完整的实现代码：

文件	原内容	新内容
`examples/blog-list-demo.md`	16 行简单说明	完整布局组件、数据加载器、使用示例
`examples/about-demo.md`	35 行简单说明	完整个人信息布局、统计数据、社交链接
`examples/links-demo.md`	21 行简单说明	完整友链管理、申请说明、网格布局
`examples/projects-demo.md`	16 行简单说明	项目展示、标签筛选、响应式网格

新增内容：

Vue 组件完整实现代码
数据加载器配置示例
响应式样式和动画效果
深色模式适配方案

📊 内容架构审计

完成网站内容架构完整性审计：

审计项	状态	说明
内容架构	✅ 优秀	11 个模块覆盖完整
Markdown 格式	✅ 规范	符合 VitePress 标准
文件完整性	✅ 完善	生态系统文件已补全
内容质量	✅ 完善	示例页面已充实
学习路径	✅ 完善	5 阶段路径清晰
实战案例	✅ 丰富	9 种类型案例

2026年04月04日

🎨 导航栏图标增强

为导航栏添加完整的 SVG 图标支持，提升视觉体验：

导航项	图标	说明
首页	home	房屋图标
学习指南	book	书本图标
参考手册	fileText	文档图标
生态系统	grid	网格图标
最佳实践	award	奖章图标
社区资源	users	用户组图标

下拉菜单图标（14x14 小图标）：

菜单项	图标
快速上手	rocket
学习路径	map
入门指南	compass
基础功能	layers
主题定制	palette
高级功能	cpu
实战案例	briefcase
交互式教程	graduationCap
API 参考	code
代码配方	terminal
插件市场	package
主题市场	layout
集成方案	zap
常见问题	helpCircle
案例展示	image
视频教程	play
学习资源	folder
标签分类	tag
文章归档	archive
更新日志	history
贡献指南	heart

实现方式：

使用 CSS ::before 伪元素 + mask-image 实现
主导航图标尺寸 16x16，下拉菜单图标尺寸 14x14
图标通过 nth-of-type 选择器精确匹配导航项
悬停/激活状态自动变色，图标与配置分离，便于维护

📚 新模块内容补充完成

完成 5 个新模块共 42 篇完整文档的编写，所有占位页面均已补充完整内容：

模块	文件数	主要内容
`/reference/`	8 篇	站点配置、运行时 API、构建 API、CLI 命令、Frontmatter 配置、主题配置、主题 API
`/recipes/`	17 篇	布局配方（404/顶部按钮/导航栏/页脚）、功能配方（评论/搜索/阅读统计）、内容配方（侧边栏/标签/归档）、集成配方（GA/RSS/PWA/Sitemap）
`/ecosystem/`	3 篇	插件市场、主题市场、集成方案索引
`/tutorial/`	12 篇	入门系列（创建站点/导航/部署）、样式定制（颜色/布局/主题）、功能扩展（博客/评论/多语言）、高级实战（插件开发/组件文档）
`/community/`	2 篇	FAQ 问答、社区索引

文档特点：

所有文档包含完整 frontmatter 元数据
大量代码示例和配置片段
实用的最佳实践建议
相关链接和参考资源

🗂️ 目录结构重构

为支持内容扩展，进行了大规模的目录结构调整：

新增模块：

模块	目录	说明
API 参考	`/reference/`	配置参考、运行时 API、CLI 命令
代码配方	`/recipes/`	常见需求的快速解决方案
生态系统	`/ecosystem/`	插件市场、主题市场、集成方案
交互式教程	`/tutorial/`	分步骤的动手实践教程
社区	`/community/`	常见问题、贡献指南

导航栏调整：

从 4 个主导航扩展为 6 个：

text

首页概览 | 学习指南 | 参考手册 | 生态系统 | 最佳实践 | 社区

新增文档数量：

新增索引文件：5 个
新增占位页面：32 个
更新配置项：侧边栏 5 个、导航 6 个、结构化数据映射 6 个

📖 API 文档迁移

将 advanced/ 中的 API 文档迁移整合到 reference/ 模块：

原位置	新位置	说明
`/advanced/api-runtime`	`/reference/runtime-api`	运行时 API 完整文档
`/advanced/api-config`	`/reference/site-config`	站点配置完整文档

更新内容：

运行时 API 文档：useData、useRoute、useRouter、usePrefetch、withBase、defineClientComponent、Content 组件
站点配置文档：基础配置、Head 配置、Markdown 配置、主题配置、构建钩子、Vite 配置
侧边栏链接更新：advanced 模块中的 API 参考指向新位置
旧文档添加迁移提示

📖 核心文档扩充

大幅扩充「什么是 VitePress」文档，内容从 2.8KB 扩展到约 15KB：

新增内容	说明
技术架构图	ASCII 架构图展示 VitePress 技术栈组成
工作流程	开发模式和生产构建的详细流程说明
详细对比矩阵	与 VuePress/Docusaurus/Nuxt Content/Next.js 的全方位对比
选型建议	不同场景下的工具选择建议
性能对比	开发启动、热更新、构建时间的基准数据
发展历程	版本演进时间线
决策矩阵	需求对照表帮助判断是否适用
检查清单扩展	新增技术掌握类检查项

📄 占位页面完善

完善了两个占位页面的内容，使其成为完整可用的功能页面：

页面	文件	主要更新
文章归档	`docs/archive.md`	使用说明、归档统计、学习建议、时间线说明
标签详情	`docs/tag.md`	标签选择方法、分类体系、热门标签速览、组合技巧

导航更新：

资源中心菜单新增「文章归档」入口
更新 activeMatch 模式以匹配新路由

📖 FAQ 内容扩展

大幅扩展常见问题文档，新增以下分类：

分类	新增问题数	覆盖内容
PWA 深度问题	5	Service Worker、图标、iOS、离线、缓存策略
动画与交互	3	页面过渡、滚动揭示、动画偏好
数据加载	2	动态数据、构建时数据
评论系统	2	Giscus、Waline 配置
图片优化	2	加载优化、路径问题
RSS 订阅	2	生成配置、内容格式
无障碍访问	3	键盘导航、屏幕阅读器、颜色对比度
调试排错	3	构建分析、开发调试、错误捕获
快速参考	3	常用命令、配置路径、错误速查表

新增问题示例：

Service Worker 更新策略详解
PWA 图标完整配置
iOS PWA 适配方案
缓存策略最佳实践
评论系统集成问题
无障碍访问指南

🎨 首页 Hero 增强

为首页 Hero 区域添加动态视觉效果，提升用户体验：

功能	说明
粒子背景	Canvas 绘制的动态粒子网络，支持鼠标交互
渐变光晕	浮动的渐变光球，增加层次感
打字机效果	增强的打字机动画，带指示器和暂停高亮
深色适配	所有效果均适配深色模式
动画减少	支持 `prefers-reduced-motion` 媒体查询

新增组件：

docs/.vitepress/theme/components/ParticleBackground.vue - 粒子背景
docs/.vitepress/theme/components/HeroBackground.vue - Hero 背景包装器

更新组件：

docs/.vitepress/theme/components/HomeEnhance.vue - 增强打字机效果

技术实现：

粒子使用 Canvas 2D API 绘制，支持连线效果
鼠标移动时粒子会被排斥，产生交互感
渐变光球使用 CSS 动画浮动
打字机效果添加了标签指示器和暂停高亮状态

📱 PWA 图标

新增完整的 PWA 图标支持，提供更好的移动端安装体验：

图标文件	尺寸	用途
`pwa-192x192.png`	192×192	Android 图标
`pwa-512x512.png`	512×512	Android 大图标
`apple-touch-icon.png`	180×180	iOS 主屏幕图标
`safari-pinned-tab.svg`	矢量	Safari 固定标签图标
`favicon.ico`	48×48	浏览器标签图标

更新内容：

使用 sharp 从 SVG 源文件自动生成 PNG 图标
更新 PWA manifest 配置，使用 PNG 图标替代 SVG
添加完整的 iOS Safari meta 标签支持
优化图标设计，添加渐变背景和阴影效果

新增脚本：

scripts/generate-pwa-icons.mjs - PWA 图标生成脚本

新增依赖：

sharp - 高性能图片处理库

🧪 测试覆盖

布局组件单元测试

新增 6 个布局组件的单元测试，测试用例总数从 152 个扩展到 313 个：

项目	说明
测试框架	Vitest 4.1.2
测试环境	happy-dom
测试工具	@vue/test-utils 2.4.6
覆盖率	@vitest/coverage-v8
测试文件	19 个测试文件
测试用例	313 个测试用例

新增布局测试：

布局组件	测试数	覆盖内容
`AboutLayout`	28	个人信息卡片、技能展示、工作经历、社交链接
`BlogListLayout`	24	文章列表、标签筛选、搜索功能、分页
`LinksLayout`	23	友链分类、链接卡片、申请友链区域
`ProjectsLayout`	29	项目筛选、精选项目、状态切换、标签过滤
`ArchiveLayout`	26	时间线渲染、年份折叠、搜索功能、统计信息
`TagLayout`	31	标签选择、URL 同步、文章过滤、图标颜色映射

新增测试文件：

docs/.vitepress/theme/layouts/AboutLayout.test.ts
docs/.vitepress/theme/layouts/BlogListLayout.test.ts
docs/.vitepress/theme/layouts/LinksLayout.test.ts
docs/.vitepress/theme/layouts/ProjectsLayout.test.ts
docs/.vitepress/theme/layouts/ArchiveLayout.test.ts
docs/.vitepress/theme/layouts/TagLayout.test.ts

核心组件单元测试扩展

新增 7 个核心组件的单元测试，测试用例总数从 48 个扩展到 152 个：

项目	说明
测试框架	Vitest 4.1.2
测试环境	happy-dom
测试工具	@vue/test-utils 2.4.6
覆盖率	@vitest/coverage-v8
测试文件	13 个测试文件
测试用例	152 个测试用例

新增测试组件：

组件	测试数	覆盖内容
`StructuredData`	6	JSON-LD 结构验证、Schema 类型检测
`KnowledgeGraph`	15	节点渲染、边连线、交互事件、布局计算
`LearningChecklist`	15	进度追踪、localStorage 持久化、重置功能
`QuizComponent`	21	问题导航、答案验证、计分系统、完成状态
`KeyboardShortcuts`	16	快捷键响应、帮助弹窗、首次访问提示
`DocFeedback`	16	有帮助/无帮助反馈、详细反馈表单、持久化
`GlobalFooter`	15	布局类型切换、备案信息、返回顶部

新增测试文件：

docs/.vitepress/theme/components/StructuredData.test.ts
docs/.vitepress/theme/components/KnowledgeGraph.test.ts
docs/.vitepress/theme/components/LearningChecklist.test.ts
docs/.vitepress/theme/components/QuizComponent.test.ts
docs/.vitepress/theme/components/KeyboardShortcuts.test.ts
docs/.vitepress/theme/components/DocFeedback.test.ts
docs/.vitepress/theme/components/GlobalFooter.test.ts

📝 内容更新

组件单元测试环境

配置 Vitest 测试框架，为核心组件编写单元测试：

项目	说明
测试框架	Vitest 4.1.2
测试环境	happy-dom
测试工具	@vue/test-utils 2.4.6
覆盖率	@vitest/coverage-v8
测试文件	6 个测试文件
测试用例	48 个测试用例

已测试组件：

组件	测试数	覆盖内容
`BackToTop`	7	渲染、显示/隐藏、滚动监听、点击事件
`CopyToast`	7	渲染、显示/隐藏、定时器、事件监听
`ProgressBar`	9	渲染、进度计算、边界条件
`LikeButton`	10	渲染、点赞/取消、localStorage、动画
`ReadingTime`	8	渲染、计算逻辑、DOM 插入
`useRouteStyles`	7	函数调用、路径处理

新增文件：

vitest.config.ts - Vitest 配置
docs/.vitepress/theme/test/setup.ts - 测试环境设置
docs/.vitepress/theme/components/*.test.ts - 组件测试
docs/.vitepress/theme/composables/*.test.ts - Composable 测试

测试命令：

npm run test - 运行测试（watch 模式）
npm run test:run - 运行测试（单次执行）
npm run test:coverage - 生成覆盖率报告

深色模式对比度优化

全面优化深色模式的颜色对比度，符合 WCAG AA 标准：

优化项目	说明
文本颜色	主文本 92% 不透明度，对比度 ≥ 4.5:1
品牌颜色	主色 #a5b4fc，对比度 ~8.5:1
背景层次	三级背景色（#0f0f10 / #18181b / #27272a）
语义色	成功/警告/危险/信息色亮度提升
代码块	代码背景、文字、高亮优化
自定义容器	边框、背景、文字颜色优化
表格	边框、斑马纹颜色优化
链接	颜色和悬停状态优化
滚动条	深色滚动条样式
选中文字	高亮颜色优化
高对比度模式	支持 `prefers-contrast: more`
减少动画	支持 `prefers-reduced-motion`

修改文件：

docs/.vitepress/theme/styles/variables.css - 深色模式变量扩展
docs/.vitepress/theme/styles/accessibility.css - 无障碍优化增强

归档页布局

新增 ArchiveLayout.vue 归档页布局：

功能	说明
时间线视图	按年份分组展示文章
年份折叠	可展开/折叠各年份
搜索过滤	搜索标题、摘要、标签
统计信息	总文章数、年份数等
响应式	移动端适配

创建页面 /archive.md。

标签详情页布局

新增 TagLayout.vue 标签详情页布局：

功能	说明
标签筛选	从 URL hash 获取标签，自动筛选文章
标签云	显示所有标签及文章数量
搜索	在当前标签中搜索文章
标签图标	为 50+ 标签配置专属图标
标签颜色	为热门标签配置专属颜色
响应式	移动端适配

创建页面 /tag.md，更新 /tags.md 链接指向新页面。

VitePress 2.0 新特性专题文档

完全重写 /guide/new-features.md 文档，基于官方 CHANGELOG 整理：

新增章节	主要内容
核心升级	Vite 6/7 支持、Shiki v3 升级
Markdown 增强	CJK 友好、数学公式、代码片段、GitHub 警告
搜索增强	本地搜索优化、DocSearch v4
主题定制	CSS 变量系统、新布局插槽、首页配置
路由导航	路由重写、路由器增强、导航增强
多语言	语言菜单增强、文本自动间距
性能优化	构建优化、运行时优化、按需加载
新增 API	站点配置、构建钩子、组合式 API
Breaking Changes	配置变更、主题变更、Markdown 变更
升级指南	依赖更新、配置检查、主题更新

FAQ 内容扩展

扩展了 /best-practices/faq.md 文档，新增 6 大分类共 20+ 个问题：

新增分类	主要内容
组件开发	SSR 兼容、样式隔离、动态导入
插件相关	自定义插件开发、常用插件推荐
SEO 相关	结构化数据、sitemap、robots.txt
环境变量	多环境配置、组件中使用环境变量
部署平台	Vercel/Netlify/Cloudflare Pages 配置
常见报错	Hydration mismatch、模块导入失败等
安全相关	XSS 防护、敏感信息保护
样式相关	主题覆盖、深色模式、移动端适配

CSS 变量文档扩展

扩展了 /theme/css-variables.md 文档，新增以下内容：

新增内容	说明
本项目自定义变量	间距、圆角、阴影、语义色系统
间距系统	`--space-xs` 到 `--space-2xl` 共 6 级间距
圆角系统	`--radius-sm` 到 `--radius-full` 共 5 级圆角
阴影系统	`--shadow-sm` 到 `--shadow-xl` 共 4 级阴影（含深色模式适配）
语义色系统	成功、警告、危险、信息 4 种语义色及其柔和背景
变量速查表	颜色、布局、扩展变量快速参考表格
使用示例	每类变量附带实际应用代码示例

README 项目说明更新

更新了项目说明文档：

更新项	说明
简介部分	改为表格形式展示统计数据（教程数、组件数等）
工程能力	新增 5 项功能说明（按需样式加载、键盘快捷键等）
项目路线图	新增章节，分为已完成/进行中/计划中三部分
项目结构	添加 `composables/` 目录说明，补充完整组件列表
导航链接	新增"路线图"快捷链接

📋 项目路线图

已完成 ✅

[x] 模块化样式架构（16 个独立文件，首屏加载减少 43%）
[x] JSON-LD 结构化数据（WebSite + TechArticle + BreadcrumbList）
[x] Critical CSS 内联注入
[x] 按路由分割样式加载（useRouteStyles）
[x] 23 个自定义 Vue 组件
[x] 4 种自定义布局
[x] PWA 离线支持
[x] 学习路径与阶段测验
[x] 知识图谱可视化
[x] CSS 变量参考文档

进行中 🚧

[ ] 评论系统集成（Giscus/Waline）
[ ] 访问统计集成（Umami/Plausible）
[x] PWA PNG 图标（192x192 / 512x512）
[x] FAQ 内容扩展（按分类细化）

计划中 📋

[ ] 学习进度云端同步
[ ] 标签详情页布局
[ ] 归档页布局
[ ] RSS Feed 订阅
[ ] 深色模式对比度优化
[x] 首页 Hero 增强（打字机效果/粒子背景）
[ ] CI/CD 自动化部署（GitHub Actions）
[ ] 组件单元测试（Vitest）
[ ] VitePress 2.0 新特性专题文档

2026年04月03日

✨ 新增功能

新手引导页

新增 /getting-started 新手引导页面，帮助用户 5 分钟快速上手 VitePress：

内容	说明
核心特点介绍	7 大核心特性表格说明
适用场景判断	适用 / 不适用场景对比
工具横向对比	与 Docusaurus、Nuxt Content、Docsify、VuePress 对比
决策树	如何选择文档工具的流程图
环境检查清单	Node.js、npm 等环境要求自检
三步快速上手	创建项目 → 启动 → 编写内容
推荐学习路径	零基础 / 迁移 / 进阶三条路径
学习小贴士	高效学习建议和常见误区

🚀 性能优化

样式文件拆分与首屏加载优化

将 style.css (30.87KB) 拆分为 16 个 模块化样式文件，优化首屏加载性能：

优化项	说明
首屏样式减少	关键样式从 30.87KB 减少至 ~17.5KB，减少 43%
加载策略优化	按优先级分级加载：关键样式同步、非关键样式延迟
缓存效率提升	模块化文件独立缓存，修改一个模块不影响其他文件

新的样式文件结构

文件	大小（约）	说明
`variables.css`	2KB	CSS 变量（品牌色、间距、阴影等）
`buttons.css`	0.5KB	按钮样式
`navigation.css`	12KB	导航样式（图标、下拉菜单）
`typography.css`	1KB	排版样式（标题、段落、链接）
`code.css`	2KB	代码块样式
`tables.css`	1KB	表格样式
`custom-blocks.css`	3KB	自定义容器样式
`toc.css`	1KB	目录样式
`utilities.css`	2KB	工具类样式
`animations.css`	5KB	动画效果
`responsive.css`	1KB	响应式适配
`accessibility.css`	1KB	无障碍优化
`print.css`	3KB	打印样式

加载策略说明

typescript

// 1. 关键样式（首屏必需，同步加载，~17.5KB）
import './styles/variables.css'      // CSS 变量（立即生效）
import './styles/buttons.css'        // 按钮交互
import './styles/navigation.css'     // 导航功能
import './styles/typography.css'     // 内容排版
import './styles/code.css'           // 代码展示

// 2. 页面组件样式（中等优先级）
import './styles/tables.css'
import './styles/custom-blocks.css'
import './styles/toc.css'
import './styles/utilities.css'

// 3. 非关键样式（可延迟加载）
import './styles/animations.css'
import './styles/responsive.css'
import './styles/accessibility.css'
import './styles/print.css'

Critical CSS 内联

将首屏关键样式（9.9KB）内联到 HTML <head> 中，消除渲染阻塞的 CSS 请求：

优化项	说明
内联大小	9.9KB / 页（压缩后的关键样式）
覆盖页面	98 个 HTML 页面全部注入
包含内容	CSS 变量、按钮、导航栏/侧边栏、排版、代码块
构建集成	`npm run build` 自动执行注入脚本

新增文件：

文件	说明
`styles/critical.css`	Critical CSS 聚合入口（@import 5 个关键模块）
`scripts/inject-critical-css.mjs`	构建后处理脚本（自动内联到所有页面）

工作流程：

bash

# 1. 构建项目
npm run build
#   ↓ 自动执行
# 2. 注入 Critical CSS 到所有 HTML <head>
node scripts/inject-critical-css.mjs

# 也可单独运行：
npm run build          # 仅构建（不注入）
node scripts/inject-critical-css.mjs  # 单独注入

🎯 交互式功能

学习检查清单组件

新增 LearningChecklist 全局 Vue 组件，为每篇教程提供交互式知识点跟踪：

功能	说明
分组展示	按知识模块分组（如概念理解、环境准备、项目创建）
进度追踪	实时显示完成进度条和百分比
持久化存储	使用 localStorage 保存学习进度，刷新不丢失
资源链接	每个检查项可附带关联资源跳转
重置功能	一键重置当前章节的学习进度

组件特性：

特性	说明
自定义复选框	美观的动画勾选效果
完成状态	全部完成后显示庆祝提示 ✨
响应式设计	适配移动端和桌面端
深色模式	自动跟随 VitePress 主题色变量

已集成检查清单的教程：

教程	检查项数	存储键
什么是 VitePress (`/guide/what-is-vitepress`)	5 项	`checklist-vp-intro`
安装与环境配置 (`/guide/installation`)	9 项	`checklist-installation`
Markdown 扩展语法 (`/basics/markdown`)	13 项	`checklist-markdown`
组件使用 (`/advanced/components`)	12 项	`checklist-components`

使用方式：

markdown

<script setup>
const checklist = [
  {
    title: '分组标题',
    items: [
      { id: 'unique-id', task: '任务描述', resources: [{ label: '参考文档', link: '/path' }] }
    ]
  }
]
</script>

<LearningChecklist title="本章检查清单" :groups="checklist" storage-key="checklist-xxx" />

新增/修改文件：

文件	操作	说明
`theme/components/LearningChecklist.vue`	新增	学习检查清单组件（~260 行）
`theme/index.ts`	修改	异步导入 + 注册全局组件
`guide/what-is-vitepress.md`	修改	添加 5 项入门概念检查清单
`guide/installation.md`	修改	添加 9 项安装配置检查清单
`basics/markdown.md`	修改	添加 13 项 Markdown 语法检查清单
`advanced/components.md`	修改	添加 12 项组件开发检查清单

📝 文档更新

文档	说明
`styles/README.md`	新增样式架构说明文档，包含优化策略和使用指南

📄 元数据完善

批量补充 Frontmatter 字段

为 92 个文档 批量补充了 SEO 和结构化数据所需的元数据字段：

新增字段	值	说明
`author`	`VitePress 学习指南`	统一作者信息
`date`	`2026-01-15`（已有则保留）	文章发布日期
`updated`	同 date 或保留原值	最后更新时间
`difficulty`	按目录自动推断	Beginner / Intermediate / Advanced

难度等级分配规则：

目录	难度	文件数
`guide/` + `basics/`	Beginner	23 篇
`best-practices/` + `theme/` + `examples/`	Intermediate	40 篇
`advanced/`	Advanced	19 篇

排除文件：首页、404、布局演示页等非教程页面

🔍 SEO 优化

JSON-LD 结构化数据集成

在 config.mts 的 transformHead 中为每个页面动态生成 JSON-LD 结构化数据：

Schema 类型	说明	适用页面
`WebSite`	站点级搜索动作	所有页面
`TechArticle`	技术文章（含分类、难度、关键词）	文档页（非首页）
`BreadcrumbList`	面包屑导航路径	所有页面

结构化数据特性：

自动推断文章分类：从 URL 路径自动匹配所属模块
动态字段映射：读取 frontmatter 中的 title、description、date、updated、difficulty、tags
发布者信息：包含组织名称、Logo、站点 URL
搜索支持：WebSite Schema 内置 SearchAction
面包屑增强：完整的三级路径

🔧 配置调整

配置项	说明
`theme/index.ts`	样式导入从单文件改为多模块导入，按优先级排序
`style.css`	删除原样式文件，拆分为模块化文件
`config.mts`	transformHead 集成 JSON-LD 结构化数据（WebSite + TechArticle + BreadcrumbList）
`styles/critical.css`	新增 Critical CSS 聚合入口（5 个关键样式模块 @import）
`scripts/inject-critical-css.mjs`	新增构建后处理脚本，自动内联关键 CSS 到 98 个页面
`package.json`	build 脚本集成注入步骤，版本升级 1.0.0 → 1.5.0
92 个 .md 文件	批量补充 frontmatter：author、date、updated、difficulty 字段

路由分割样式

按路由分割样式加载（Route-based CSS Splitting）

将 16 个 CSS 文件从全部同步加载改为根据页面路径按需动态加载：

Bundle	大小	加载时机	包含样式	适用页面
A: Global Core	~2.5KB	始终同步	variables.css	所有页面
B: Base UI	~19KB	非首页动态	buttons, navigation, typography, responsive, utilities	文档/特殊页
C: Content	~5KB	文档内容页动态	code, tables, custom-blocks, toc	guide/basics/theme/advanced/bp
D: Home	~8.7KB	仅首页动态	home.css	首页 /
E: Special Pages	~16.6KB	特殊页动态	components, pages	videos/tags/changelog 等
F: Enhancement	~6KB	空闲时延迟	animations, accessibility, print	所有页面

优化效果：

场景	优化前	优化后	减少
首页首屏	~58KB (16文件)	~2.5KB + 8.7KB + 内联9.9KB	~63%
文档内容页	~58KB (16文件)	~2.5KB + 19KB + 5KB + 内联9.9KB	~47%
特殊页面	~58KB (16文件)	~2.5KB + 19KB + 16.6KB + 内联9.9KB	~26%

新增/修改文件：

文件	操作	说明
theme/composables/useRouteStyles.ts	新增	路由分割样式 composable (~170 行)
theme/index.ts	修改	移除静态导入，改为仅同步 variables + 调用 useRouteStyles

2026年04月01日

📚 新增文档

根据内容覆盖分析和与 VitePress 官方文档对比，补充了以下文档：

教程	说明
路由重写 `/guide/rewrites`	URL 重写、路径映射、多语言路由配置
Meta 与 SEO 配置 `/basics/meta-seo`	Open Graph、Twitter Card、结构化数据
图片优化指南 `/best-practices/image-optimization`	压缩、懒加载、WebP、响应式图片
开源项目文档站 `/examples/open-source-docs`	GitHub 集成、版本管理、贡献指南
SSR 兼容性 `/guide/ssr-compatibility`	SSR 常见问题、解决方案、最佳实践
MPA 模式 `/guide/mpa-mode`	多页面应用模式配置、适用场景、迁移指南
llms.txt 支持 `/guide/llms-txt`	AI 搜索优化、结构化文档索引生成
Carbon Ads 集成 `/advanced/carbon-ads`	广告变现集成、配置方式、样式定制

📝 内容更新

Badge 组件文档扩展

扩展了 /advanced/components 中 Badge 组件的文档：

导航栏中使用徽章的配置方法
徽章类型详细说明表格
CSS 变量自定义颜色样式

Team Page 配置新增

在 /team 页面新增 VitePress 官方 Team Components 使用指南：

Team Members 数据结构定义
VPTeamMembers 组件使用
VPTeamPage 完整布局示例
自定义样式配置

为所有文章添加标签

为项目中 83 篇文章添加了合适的标签，方便读者按标签浏览内容。

目录	文件数	标签示例
`guide/`	7	入门、安装、迁移、SSG
`basics/`	10	配置、Markdown、路由、导航栏
`advanced/`	18	部署、国际化、搜索、插件
`theme/`	15	主题、CSS、布局、Vue
`best-practices/`	12	SEO、性能、测试、CI/CD
`examples/`	9	实战案例、博客、作品集
根目录	12	学习路径、资源、案例

Tags 页面更新

更新项	说明
标签云	更新标签数量统计，调整大小显示
详细分类	从 11 个扩展到 15 个分类
其他标签	新增 30+ 个细分标签展示区
统计数据	文章数量更新为 83，标签分类更新为 60+

🐛 问题修复

代码块嵌套问题修复

修复了代码示例中代码块嵌套导致的 Markdown 解析错误。

文件	修复数量
`basics/custom-containers.md`	5 处
`contributing.md`	1 处
`best-practices/faq.md`	1 处

修复方法：将 ```markdown 改为 ````markdown（4个反引号），确保内部包含 3 个反引号的代码能正确嵌套显示。

表格格式问题修复

修复了表格使用 || 开头导致的格式错误，涉及 9 个文件，共 101 处。

文件	修复数量
`theme/layout-slots.md`	29 处
`best-practices/plugins.md`	14 处
`theme/default-theme.md`	13 处
`theme/testing.md`	11 处
`theme/blog-theme-tutorial.md`	8 处
`theme/vue-components.md`	7 处
`theme/performance.md`	7 处
`theme/css-variables.md`	6 处
`theme/community-themes.md`	6 处

修复方法：将 || 开头的表格行改为 | 开头，符合 VitePress Markdown 表格规范。

🔧 配置调整

配置项	说明
data-loading.md	修复重复的 frontmatter 内容

2026年03月31日

✨ 新增功能

新增主题开发进阶系列教程

教程	说明
Vue 组件开发指南 `/theme/vue-components`	Vue 3 组件开发、组件注册方式、组件通信、响应式数据、最佳实践
主题架构原理 `/theme/architecture`	VitePress 主题系统架构、核心概念、生命周期钩子、构建流程详解
主题开发实战 `/theme/blog-theme-tutorial`	从零开发博客主题完整教程，包含项目规划、核心组件开发、部署
主题打包与发布 `/theme/theme-publishing`	项目结构、打包配置、npm 发布流程、版本管理、自动化发布
主题性能优化 `/theme/performance`	加载优化、渲染优化、构建优化、Core Web Vitals
主题测试指南 `/theme/testing`	单元测试、组件测试、E2E 测试、CI 集成、覆盖率统计
主题开发常见问题 `/theme/theme-faq`	25+ 常见问题解答，涵盖配置、样式、组件、构建、SEO、部署等
主题开发工具 `/theme/dev-tools`	VS Code 扩展、开发工具、调试技巧、实用脚本

新增教程

教程	说明
TypeScript 深度集成指南 `/advanced/typescript-guide`	类型声明、类型安全组件、数据加载类型、构建时类型检查等
Headless CMS 集成 `/advanced/cms-integration`	Strapi、Notion、Contentful 三种 CMS 集成方案，含 CI/CD 自动同步
评论系统集成 `/advanced/comments-integration`	Giscus、Waline、Twikoo 详细对比与集成指南，含迁移教程
国际化实战案例 `/advanced/i18n-practice`	完整的中英文多语言站点搭建，含翻译管理和自动翻译工具
更多部署平台 `/advanced/deployment-platforms`	Railway、Render、Zeabur、Fly.io 等新兴平台部署教程
站点测试指南 `/best-practices/testing`	Vitest 单元测试、Playwright E2E 测试、快照测试、可访问性测试
自定义容器语法 `/basics/custom-containers`	提示框、警告框、代码组、自定义容器样式等完整教程
社区主题使用指南 `/theme/community-themes`	社区主题推荐、安装配置、主题开发指南

新增实战案例

案例	说明
个人作品集搭建 `/examples/portfolio`	第 8 个实战案例，涵盖首页设计、项目展示、技能矩阵、经历时间线、联系方式
电商文档站搭建 `/examples/ecommerce-docs`	第 7 个实战案例，涵盖商品文档、API 文档、帮助中心、开发者指南

📝 内容更新

更新项	说明
版本标记完善	主题开发相关文档全部添加版本说明和支持环境信息
布局插槽文档	所有插槽表格添加版本要求列（v0.22.0+）
插件扩展文档	插件表格添加 VitePress 版本和 Node.js 版本要求
案例展示扩充	新增 VueUse、Pinia、Nuxt、Vitest、UnoCSS、Vue Router、Vue Macros 等 10+ 个社区案例
案例展示扩充	新增 Arco Design、NutUI、Varlet 等 4 个组件库案例
案例展示扩充	新增博客、作品集、简历等个人站点案例分类
示例仓库链接修复	`examples/index.md` 占位符链接替换为实际仓库地址
视频教程时间戳	`videos.md` 全部 6 个视频添加章节时间戳导航
学习资源扩充	`resources.md` 插件列表从 4 个扩展至 15+ 个，新增部署平台推荐

🔧 配置调整

配置项	说明
侧边栏重构	主题定制模块拆分为三个分组：「主题定制」「主题开发进阶」「优化与测试」
侧边栏更新	主题开发进阶新增 4 个入口（Vue 组件、架构原理、开发实战、打包发布）
侧边栏更新	优化与测试新增 4 个入口（性能优化、测试指南、常见问题、开发工具）
侧边栏更新	基础功能新增「自定义容器语法」入口（带「新」标签）
侧边栏更新	高级功能新增「国际化实战案例」入口（带「新」标签）
侧边栏更新	集成与扩展新增「TypeScript 集成」「CMS 集成」「评论系统」「更多部署平台」入口
侧边栏更新	实战案例新增「个人作品集搭建」入口（带「新」标签）
侧边栏更新	实战案例新增「电商文档站搭建」入口（带「新」标签）
侧边栏更新	最佳实践新增「站点测试指南」入口（带「新」标签）
首页更新	最新特性区域扩充至 7 个新特性卡片

2026年03月28日

✨ 新增功能

新增教程

教程	说明
SSG 工具对比 `/guide/ssg-comparison`	VitePress 与 Nuxt Content、Docusaurus、Docsify、VuePress 的详细对比分析
插件开发指南 `/advanced/plugin-development`	VitePress 插件开发完整教程，涵盖 Vite 插件、Markdown 插件、构建钩子等

EdgeOne Pages 部署支持

内容	说明
CNB 云构建配置	完整的 `cnb.yml` 配置示例
EdgeOne Pages 配置	`edgeone.json` 配置文件示例
边缘函数示例	自定义重定向规则
部署优势对比	EdgeOne Pages 与其他平台的对比

📝 内容更新

更新项	说明
部署教程增强	`deployment.md` 新增腾讯云 EdgeOne Pages 部署章节
学习路径更新	入门阶段添加 SSG 工具对比教程，高级阶段添加插件开发教程
学习时间调整	总学习时长更新为 20 小时

🔧 配置调整

配置项	说明
侧边栏更新	入门指南添加「SSG 工具对比」入口
侧边栏更新	高级功能添加「插件开发」入口（带「新」标签）

2026年03月27日

🚀 功能优化

导航栏优化

优化项	说明
移除 English 入口	导航栏移除外部英文链接，聚焦中文文档
移除版本切换器	移除 VersionSwitcher 组件及相关配置，简化导航

域名统一管理

优化项	说明
SITE_URL 集中配置	所有域名统一在 `config.mts` 的 `SITE_URL` 常量管理
REPO_URL 集中配置	仓库链接统一在 `config.mts` 的 `REPO_URL` 常量管理
组件动态读取	StructuredData、LinksLayout、GlobalFooter、Contribution 从配置读取域名

SEO 优化

优化项	说明
Canonical URL	通过 `transformHead` 为每个页面动态生成 canonical 链接
结构化数据域名	StructuredData 中所有 URL 从占位域名替换为实际域名
robots.txt	Sitemap URL 同步为实际域名

组件加载优化

优化项	说明
异步组件	17 个非首屏组件改为 `defineAsyncComponent` 异步加载
首屏关键组件	仅 8 个首屏关键组件保持同步加载

🗑️ 移除功能

移除项	说明
RSS 订阅配置	移除不存在的 `/rss.xml` 引用，避免 404
VersionSwitcher 组件	组件及配置已清理
Contribution 错误链接	"参与贡献"链接从上游 `vuejs/vitepress` 修正为本项目仓库

🔧 配置调整

配置项	说明
themeConfig.siteUrl	新增站点域名配置字段，类型声明已补充
env.d.ts 类型扩展	新增 `siteUrl` 类型声明
socialLinks / editLink	改为引用 `REPO_URL` 常量

🔧 工程优化

robots.txt 修复

优化项	说明
移除 JS/JSON 爬取限制	删除 `Disallow: /.js$` 和 `Disallow: /.json$`，修复搜索引擎无法正常渲染 SPA 页面的问题

样式文件拆分

优化项	说明
style.css 拆分	主文件从 2255 行缩减至 1036 行（减少 54%），拆分为 4 个职责明确的 CSS 文件
styles/components.css	组件全局样式（离线提示、复制提示、快捷键面板、阅读进度等），171 行
styles/home.css	首页专属样式（统计卡片、快速导航、版本徽章等），492 行
styles/pages.css	页面级样式（视频页、标签页、团队页、案例页、404 页等），477 行
合并重复打印样式	原文件中两处 `@media print` 块合并为一处完整版本
合并重复变量定义	原文件中 3 处 `:root` 变量块合并为 1 处

2026年03月26日

✨ 新增功能

新增组件

组件	说明
HomeEnhance	首页动态化增强，Hero 名称渐变流光、标语轮播、图片浮动动画、按钮入场动画
KnowledgeGraph	知识图谱可视化组件，交互式节点图展示 VitePress 知识体系
PageTransition	页面切换过渡动画，CSS class 驱动的淡入淡出效果
ScrollReveal	滚动揭示动画，基于 IntersectionObserver 的元素入场效果
VersionSwitcher	版本切换器，导航栏中的 VitePress 版本快速切换

新增页面

页面	说明
企业官网搭建 `/examples/corporate-site`	第 6 个实战案例，涵盖专业首页 Hero、产品展示、联系表单、SEO 结构化数据

GlobalFooter 全面增强

功能	说明
快速链接区域	四分类快速链接（学习指南、实战案例、最佳实践、社区）
RSS 订阅	页脚 RSS 订阅入口
返回顶部	平滑滚动返回顶部按钮
社交媒体链接	GitHub、B站等社交平台入口

ReadingProgress 增强

功能	说明
阅读历史	记录最近 15 条阅读历史，支持标题映射显示
历史面板	点击即可查看和跳转历史页面

🚀 功能优化

导航与侧边栏

优化项	说明
侧边栏折叠	入门指南、基础功能、主题定制、高级功能、实战案例分组默认折叠
导航扩展	新增"更多"菜单，包含标签分类、文章归档、贡献者、更新日志入口
版本切换器	导航栏集成 VitePress 版本切换功能
导航精简	资源中心菜单从 9 项精简至 5 项

视频教程优化

优化项	说明
内嵌播放	视频从外链卡片改为 iframe 内嵌播放器，支持 B站和 YouTube
用户体验	无需跳转即可直接观看教程视频

代码示例优化

优化项	说明
StackBlitz 集成	内嵌 StackBlitz 在线编辑器，无需本地安装即可体验 VitePress
快速模板	新增最小化模板和完整模板，一键复制即可使用

📝 内容更新

更新项	说明
首页统计	实战案例数量更新 5 → 6，添加版本追踪区域和 scroll-reveal 动画
学习路径	QuizComponent 改用 script setup 变量引用，修复构建错误；新增知识图谱和 mermaid 流程图
错误处理	新增"常见踩坑指南"章节（base 配置、cleanUrls、CSS 优先级、VuePress 迁移、性能优化等）
FAQ 扩充	新增 PWA 相关（Service Worker、缓存策略）、多语言问题、VuePress 迁移、Markdown 高级问题等
贡献指南	新增"贡献者荣誉"体系（6 个等级、认可方式、季度贡献之星）和"贡献统计"章节
API 文档	api-config.md 和 api-runtime.md 新增快速导航目录
案例索引	examples/index.md 新增企业官网示例入口

🎨 样式优化

样式类	说明
Hero 动画	名称渐变流光、图片浮动、按钮交错入场动画
Features 动画	卡片交错入场效果
滚动揭示	`.scroll-reveal` 类，元素进入视口时淡入上滑
页面过渡	淡入淡出页面切换效果
页脚样式	多列链接布局、分隔线、返回顶部按钮样式
阅读历史	弹出面板、列表项、时间戳样式
版本切换器	导航栏下拉选择器样式
知识图谱	SVG 节点图、交互高亮、连线和标签样式
视频嵌入	iframe 嵌入容器响应式适配
演练场	StackBlitz 编辑器嵌入容器样式

🐛 问题修复

修复项	说明
QuizComponent 构建	修复多行内联属性导致 VitePress markdown-to-SFC 编译失败，改用 script setup 变量引用
学习路径重复	删除阶段三重复的教程列表和测试内容
双重页脚	移除冗余的 DocFooter 组件

🔧 配置调整

配置项	说明
全局组件注册	新增 KnowledgeGraph 组件全局注册
插槽配置	新增 `nav-bar-content-before` 和 `nav-screen-content-before` 插槽

2026年03月14日

✨ 新增功能

用户体验组件

组件	说明
ReadingProgress	学习进度追踪，使用 localStorage 记录已读页面
RelatedPosts	相关文章推荐，基于标签匹配推荐相关内容
KeyboardShortcuts	键盘快捷键支持（`?` 显示帮助，`Ctrl+K` 搜索）
OfflineIndicator	离线提示条，断网时自动显示
CopyToast	代码复制成功 Toast 提示
QuizComponent	学习测验组件，支持多题目和答案解析

新增页面

页面	说明
视频教程 `/videos`	B站/YouTube 视频资源汇总页面
案例展示 `/showcase`	展示优秀 VitePress 站点案例
代码示例 `/playground`	在线体验 VitePress 功能

🔧 配置调整

PWA 完整配置

配置项	说明
manifest	应用名称、图标、主题色完整配置
workbox	缓存策略、自动更新、Service Worker 配置
离线支持	支持离线浏览文档内容

构建优化

优化项	说明
chunkSizeWarningLimit	提高到 1000KB，减少警告
类型声明	添加 `env.d.ts` Vue 组件类型声明

🚀 功能优化

导航增强：资源中心菜单添加"视频教程"入口，带"新"标识
首页优化：快速导航扩展为 6 项，新增视频教程和代码示例入口
学习路径：添加阶段测试 Quiz 组件，增强互动学习体验
主题集成：所有新组件已集成到主题布局中
页脚统一：整合页脚与备案信息为统一 GlobalFooter 组件

🎨 样式优化

样式类	说明
离线提示条	固定顶部显示，橙色背景
复制 Toast	右下角弹出动画效果
移动端导航	底部固定导航栏（已移除，使用默认导航）
快捷键面板	居中弹窗样式
学习进度	侧边栏底部进度显示
动画效果	淡入、滑入、缩放动画类

🐛 问题修复

修复 index.ts 语法错误（括号不匹配）
修复 ReadingProgress.vue SSR 兼容问题
修复 OfflineIndicator.vue SSR 兼容问题
修复 PWA 配置调用方式错误
移除无效的 manualChunks 配置

2026年03月13日

✨ 新增功能

PWA 支持

功能	说明
离线访问	支持 PWA 离线浏览文档
安装提示	提供网站安装到桌面的引导
自动更新	Service Worker 自动更新机制

代码示例仓库

内容	说明
示例仓库入口	`/examples/` 提供所有示例项目的代码仓库链接
克隆与下载	提供 GitHub 克隆和 ZIP 下载方式
贡献指南	示例代码的贡献和改进流程

进阶挑战题

为 5 个实战案例添加了进阶挑战任务：

案例	挑战数量	难度范围
博客搭建	6 个挑战	⭐⭐ ~ ⭐⭐⭐⭐
组件库文档	6 个挑战	⭐⭐⭐ ~ ⭐⭐⭐⭐
API 文档站	6 个挑战	⭐⭐ ~ ⭐⭐⭐⭐⭐
个人简历站	6 个挑战	⭐⭐⭐ ~ ⭐⭐⭐⭐
知识库站点	6 个挑战	⭐⭐⭐ ~ ⭐⭐⭐⭐⭐

📝 内容更新

首页统计更新：核心教程 30+ → 37+，学习时长 20h → 25h+
学习路径更新：添加代码示例仓库和 PWA 支持教程入口
侧边栏优化：新增代码示例入口，新增 PWA 支持菜单项

🔧 配置调整

添加 @vite-pwa/vitepress 依赖
配置 PWA manifest 和 Service Worker
添加 PWA 相关的 meta 标签

2026年02月28日

✨ 新增功能

新增布局组件

布局	说明
BlogListLayout	博客文章列表布局，支持标签筛选和搜索
AboutLayout	关于页面布局，支持个人信息、技能、经历展示
LinksLayout	友情链接布局，支持分类展示和申请说明
ProjectsLayout	项目展示布局，支持精选项目和状态筛选

使用方式：在 frontmatter 中设置 layout: blog-list、layout: about、layout: links、layout: projects 即可调用。

新增组件

组件	说明
LikeButton	文章点赞功能，支持飘心动画效果
ImageZoom	图片点击缩放灯箱效果
Contribution	贡献者展示组件

新增页面

页面	说明
标签分类 `/tags`	按标签浏览文章，支持标签云展示
文章归档 `/archive`	按时间线浏览文章列表
贡献者 `/contributors`	展示项目贡献者和参与情况

新增教程

教程	说明
自定义布局 `/theme/custom-layouts`	布局组件使用教程和配置说明
VitePress 新特性	介绍 VitePress 2.0/3.0 的新功能和改进
Algolia 搜索集成	完整的 Algolia DocSearch 集成教程
组件库文档实战	扩充完整的组件库文档搭建教程

🚀 功能优化

首页增强：新增快速导航、最新特性、用户反馈三个功能区域
导航优化：添加标签分类、文章归档、贡献者导航入口
侧边栏优化：添加新特性、Algolia 搜索等入口
分享按钮优化：ShareButton 组件独立运行，不再依赖 ReadingTime 组件

🎨 样式优化

链接样式：首页所有链接取消下划线，提升视觉体验
SSR 兼容：修复组件在服务端渲染时的 localStorage 错误
页脚优化：添加公安网安备案信息，符合国内网站合规要求

🐛 问题修复

修复 Markdown 中嵌套 Vue 模板语法的构建错误
修复 localStorage 在 SSR 构建时的访问错误

2026年02月27日

✨ 新增功能

SEO 优化指南：完整的搜索引擎优化教程
CI/CD 自动化部署：GitHub Actions、Vercel、Netlify 等部署方案

🚀 功能优化

导航菜单简化：移除 SVG 图标，采用纯文字导航，参考默认主题风格
激活状态优化：导航激活状态增加底部下划线指示器

🎨 样式优化

配色方案重构：参考 VitePress 默认主题的 3 级色阶系统，完善明亮/深色模式配色
深色模式品牌色调整：#a5b4fc 作为深色模式主色，确保对比度
按钮配色更新：使用 CSS 变量引用，便于统一管理

🐛 问题修复

修复深色模式下品牌色对比度不足的问题
修复导航悬停效果不一致的问题

2026年02月15日

✨ 新增功能

自定义 404 页面，提供更好的用户体验和推荐导航
面包屑导航组件，方便用户了解当前位置
阅读时间统计组件，预估文章阅读时长
返回顶部按钮，优化长页面浏览体验
结构化数据支持，提升搜索引擎优化

🚀 功能优化

优化深色模式样式适配，统一品牌色彩
改进首页统计区域展示效果
优化导航栏图标系统，支持 SVG 图标
完善移动端响应式布局

📝 内容更新

完善团队介绍页面内容
更新学习路径中的工具推荐
扩充学习资源页面

🐛 问题修复

修复部分页面在深色模式下的样式问题
修复导航栏激活状态显示不一致的问题

2026年01月01日

首次发布

本项目正式上线，提供以下核心内容：

入门指南

教程	说明
什么是 VitePress	VitePress 简介和核心特点
安装与环境配置	开发环境搭建指南
项目结构解析	目录结构和文件说明
创建第一个页面	快速上手实践
从 VuePress 迁移	迁移指南和注意事项

基础功能

教程	说明
Markdown 扩展语法	VitePress 增强的 Markdown 功能
Frontmatter 配置	页面级配置说明
配置文件详解	完整的配置选项说明
导航栏配置	自定义导航栏
侧边栏配置	多级侧边栏设置
静态资源管理	图片、样式等资源处理
路由详解	文件路由机制

主题定制

教程	说明
默认主题配置	使用和配置默认主题
自定义主题	开发个性化主题
CSS 变量覆盖	样式定制方法
布局插槽	扩展布局功能
菜单图标配置	导航图标设置

高级功能

教程	说明
组件使用	在 Markdown 中使用 Vue 组件
数据加载	动态数据获取和处理
多语言支持	国际化配置
搜索功能	本地搜索和第三方搜索
构建优化	构建性能优化
部署与发布	多平台部署指南
站点统计	访问统计和分析
RSS 与站点地图	SEO 增强

实战案例

案例	说明
博客搭建	个人技术博客搭建
组件库文档	组件文档站开发
API 文档站	REST API 文档
个人简历站	在线简历网站
知识库站点	团队知识库搭建

最佳实践

教程	说明
性能优化	网站性能优化建议
常见问题	FAQ 汇总
插件扩展	常用插件推荐
速查表	常用配置速查

开发计划

近期计划

功能	状态	预计时间
视频教程内容	✅ 已完成	2026年3月
更多实战案例	🚧 进行中	2026年3月
英文版文档	📋 规划中	2026年4月
互动式测验系统	✅ 已完成	2026年3月
键盘快捷键支持	✅ 已完成	2026年3月

长期规划

功能	描述	状态
互动式教程系统	在线代码编辑和运行	💡 构思中
在线代码演练场	实时代码演示环境	✅ 已完成
社区贡献者展示	展示项目贡献者	✅ 已完成
版本切换功能	支持多版本文档	❌ 已移除
标签分类系统	按标签浏览文章	✅ 已完成
文章归档页面	按时间线展示文章	✅ 已完成
PWA 离线支持	支持离线访问文档	✅ 已完成
进阶挑战题	实战案例进阶练习	✅ 已完成
学习进度追踪	记录用户学习进度	✅ 已完成
相关文章推荐	基于标签推荐相关文章	✅ 已完成
案例展示页面	优秀站点案例展示	✅ 已完成
移动端优化	响应式导航适配	✅ 已完成

贡献指南

如果你发现文档有误或希望补充内容，欢迎通过以下方式参与：

提交 Issue - 报告问题或提出建议
Pull Request - 直接参与代码贡献
讨论交流 - 在 GitHub Discussions 分享想法

变更类型说明

本更新日志使用以下 Emoji 标记标识不同类型的变更：

标记	类型	说明
✨	新增功能	全新功能或重要特性
🚀	功能优化	现有功能的改进和优化
📝	内容更新	文档内容的补充和完善
🎨	样式优化	UI/UX 和视觉效果的改进
🐛	问题修复	Bug 修复和问题解决
🔧	配置调整	配置文件或构建相关调整
⚠️	弃用提醒	即将移除或变更的功能
💥	破坏性变更	需要用户注意的不兼容变更

保持更新

本教程会持续更新，建议 Star 项目以获取最新动态！

更新日志 ​

2026年04月10日 ​

📝 生态系统模块深度扩充 ​

👥 社区板块内容扩充 ​

🔧 配置更新 ​

2026年04月08日 ​

🧹 内容清理与架构优化 ​

📊 Mermaid 图表深入教程 ​

🔄 版本升级指南 ​

📦 生态系统扩充与去重叠 ​

2026年04月07日 ​

📊 性能基准测试报告 ​

🏢 企业级案例研究 ​

🔧 故障排查手册完善 ​

📦 迁移专题指南更新 ​

📚 模块索引页面扩充 ​

🏷️ Tags 风格统一 ​

📝 Frontmatter 元数据完善 ​

📄 项目说明文件更新 ​

📑 目录索引页面完善 ​

👥 社区板块内容扩充 ​

🔧 Markdown 格式规范修复 ​

表格格式修复 ​

代码块语言标识修复 ​

🔗 教程导航链接完善 ​

⚙️ 配置文件更新 ​

2026年04月06日 ​

📝 内容优化 ​

重复文档清理 ​

🌐 生态系统模块完善 ​

📐 示例页面完善 ​

📊 内容架构审计 ​

2026年04月04日 ​

🎨 导航栏图标增强 ​

📚 新模块内容补充完成 ​

🗂️ 目录结构重构 ​

📖 API 文档迁移 ​

📖 核心文档扩充 ​

📄 占位页面完善 ​

📖 FAQ 内容扩展 ​

🎨 首页 Hero 增强 ​

📱 PWA 图标 ​

🧪 测试覆盖 ​

布局组件单元测试 ​

核心组件单元测试扩展 ​

📝 内容更新 ​

组件单元测试环境 ​

深色模式对比度优化 ​

归档页布局 ​

标签详情页布局 ​

VitePress 2.0 新特性专题文档 ​

FAQ 内容扩展 ​

CSS 变量文档扩展 ​

README 项目说明更新 ​

📋 项目路线图 ​

已完成 ✅ ​

进行中 🚧 ​

计划中 📋 ​

2026年04月03日 ​

✨ 新增功能 ​

新手引导页 ​

🚀 性能优化 ​

样式文件拆分与首屏加载优化 ​

新的样式文件结构 ​

加载策略说明 ​

Critical CSS 内联 ​

🎯 交互式功能 ​

学习检查清单组件 ​

📝 文档更新 ​

📄 元数据完善 ​

批量补充 Frontmatter 字段 ​

🔍 SEO 优化 ​

JSON-LD 结构化数据集成 ​

🔧 配置调整 ​

路由分割样式 ​

按路由分割样式加载（Route-based CSS Splitting） ​

2026年04月01日 ​

📚 新增文档 ​

📝 内容更新 ​

Badge 组件文档扩展 ​

更新日志

2026年04月10日

📝 生态系统模块深度扩充

👥 社区板块内容扩充

🔧 配置更新

2026年04月08日

🧹 内容清理与架构优化

📊 Mermaid 图表深入教程

🔄 版本升级指南

📦 生态系统扩充与去重叠

2026年04月07日

📊 性能基准测试报告

🏢 企业级案例研究

🔧 故障排查手册完善

📦 迁移专题指南更新

📚 模块索引页面扩充

🏷️ Tags 风格统一

📝 Frontmatter 元数据完善

📄 项目说明文件更新

📑 目录索引页面完善

👥 社区板块内容扩充

🔧 Markdown 格式规范修复

表格格式修复

代码块语言标识修复

🔗 教程导航链接完善

⚙️ 配置文件更新

2026年04月06日

📝 内容优化

重复文档清理

🌐 生态系统模块完善

📐 示例页面完善

📊 内容架构审计

2026年04月04日

🎨 导航栏图标增强

📚 新模块内容补充完成

🗂️ 目录结构重构

📖 API 文档迁移

📖 核心文档扩充

📄 占位页面完善

📖 FAQ 内容扩展

🎨 首页 Hero 增强

📱 PWA 图标

🧪 测试覆盖

布局组件单元测试

核心组件单元测试扩展

📝 内容更新

组件单元测试环境

深色模式对比度优化

归档页布局

标签详情页布局

VitePress 2.0 新特性专题文档

FAQ 内容扩展

CSS 变量文档扩展

README 项目说明更新

📋 项目路线图

已完成 ✅

进行中 🚧

计划中 📋

2026年04月03日

✨ 新增功能

新手引导页

🚀 性能优化

样式文件拆分与首屏加载优化

新的样式文件结构

加载策略说明

Critical CSS 内联

🎯 交互式功能

学习检查清单组件

📝 文档更新

📄 元数据完善

批量补充 Frontmatter 字段

🔍 SEO 优化

JSON-LD 结构化数据集成

🔧 配置调整

路由分割样式

按路由分割样式加载（Route-based CSS Splitting）

2026年04月01日

📚 新增文档

📝 内容更新

Badge 组件文档扩展