Appearance
本站的 SEO 落地实践：从 Docsify 迁到 VitePress
最后更新：2026-08-19
本主题要回答的问题
- 本站原来用 Docsify 时，SEO 出了哪些问题？
- 迁移到 VitePress 后，技术上具体解决了什么？
- 一个"内容站 + SSG"的 SEO 改造清单长什么样？
本文是前端技术与SEO 主题在本站的交叉落地案例。完整的迁移技术背景见 VitePress 专篇。
一、迁移前的 SEO 问题（Docsify 时代）
Docsify 是运行时渲染的单页文档站：浏览器下载 Markdown 再渲染成页面。对 SEO 来说，它踩了前端框架与 SEO里"纯 SPA"的所有坑：
| 问题 | 对 SEO 的影响 |
|---|---|
| 无预渲染，正文靠 JS | 爬虫可能只拿到空壳，正文不被索引 |
| 无静态 meta / canonical | 缺 title/描述信号、URL 不唯一 |
| 无 sitemap 与结构化数据 | 页面发现慢、无富摘要 |
| 运行时有外部请求（PlantUML） | 加载慢，影响体验与 LCP |
二、迁移后的 SEO 改造（VitePress 时代）
VitePress 是构建期渲染（SSG），天然把"正文落进静态 HTML"。在此基础上本站做了针对性 SEO 强化：
| SEO 动作 | 实现方式 | 收益 |
|---|---|---|
| 构建期渲染全文 | VitePress SSG 把 Markdown 编译成静态 HTML | 爬虫零 JS 也能索引到正文 |
| 每页静态 meta | frontmatter + 构建期生成 title/description | 排名 + CTR 信号就位 |
| canonical 统一 URL | 每页 <link rel="canonical"> | 消除重复 URL 权重稀释 |
| og:url / og:meta | 每页开放图谱标签 | 社交分享摘要规范 |
| cleanUrls | 统一 URL 形态（无 .md 尾巴） | URL 唯一、可读、无重复 |
| 本地搜索替代运行时搜索 | VitePress localSearch | 减少运行时 JS 依赖 |
| 构建期渲染 PlantUML | 构建期内联图片到 public/ | 运行时零外部请求，加载快 |
| 语义化结构 | VitePress 生成 h1/h2、nav、面包屑 | 内容可解析 |
三、文档站的 SEO 落地清单
结合本站实践，一份**"内容站 + SSG"的 SEO 检查清单**：
1. 技术 SEO（可索引性）
- [x] 构建期生成完整静态 HTML（非运行时渲染）
- [x] 每页唯一
<title>+description - [x] 每页
canonical统一唯一 URL - [x]
cleanUrls+ URL 可读，无参数重复 - [x] 提交
sitemap.xml - [x]
robots.txt声明抓取范围
2. 结构化与语义
- [ ] 关键内容页加 JSON-LD 结构化数据（文章/教程/FAQ）
- [x] 语义化标签（标题层级、
nav、article） - [x] 站内交叉链接形成主题集群
3. 性能与体验（Core Web Vitals）
- [x] 首屏无 JS 渲染等待（SSG 静态 HTML）
- [x] 静态资源加指纹缓存
- [x] 构建期处理图片（PlantUML 落盘）减少运行时请求
- [ ] 图片懒加载 + 尺寸预留（防 CLS）
4. 测量与验证
- [ ] 接入 Search Console，看索引覆盖率
- [ ] 用爬虫渲染测试验证"爬虫视角"HTML 是否含正文
- [ ] 定期检查死链与重复 URL
四、经验总结
| 教训 | 结论 |
|---|---|
| 运行时渲染的文档站 SEO 天生受限 | 文档/博客应优先选 SSG |
| 内容必须进首屏 HTML | 别把正文押在 JS 执行上 |
| 技术 SEO 是地基 | 内容再好，索引不了 = 0 |
| SEO 可测量 | 迁移前后用 Search Console 对比收录与性能 |
一句话总结
本站的迁移证明了一个可复用的结论：文档站这类"内容构建期已知"的站点，从运行时渲染（Docsify）迁到构建期渲染（VitePress/SSG）是 SEO 的根本性修复——正文落进静态 HTML，再补上 canonical、sitemap、结构化数据、CWV 优化，就构成了一套完整、可测量、可持续的内容站 SEO 方案；这也再次印证：SEO 的成败，往往在"选技术方案"的那一刻就已注定。