VitePress

VitePress 是静态站点生成器，面向技术文档，构建层用 Vite，写作层用 Markdown，官方给出的适用范围是文档站、博客与营销页^[1]。它和 Hugo 那类单二进制路线不同，装它要 Node 环境，主题与扩展都走 Vue 生态。

产物的两副面孔

构建阶段把每篇 Markdown 编译成静态 HTML，写进输出目录^[2]。浏览器第一次拿到的是这层 HTML，文字已经在里面，抓取不必执行脚本。脚本加载完成后，站点切到单页应用的形式，站内跳转不再整页刷新^[1]。

风险集中在两处。一处是站内链接指向了没有静态化产物的路由；另一处是图片与附件写了错路径，页面能看，抓取读不到。

部署要配对的三件事

输出目录   docs/.vitepress/dist
站点前缀   base，形如 /repo/

放在子路径发布必须设前缀，不设时资源与链接仍指向根^[2]。

静态资源按官方建议给长缓存，参数是 max-age=31536000,immutable^[2]。这条与收录无关，影响的是回访速度与性能指标。

用 nginx 托管时要加回退规则，把不带后缀的地址指到 $uri.html，访问与抓取才拿得到对应文件^[2]。

官方画出的使用分界

网页应用若带复杂客户端交互与数据渲染，就不在它的适用范围内，官方建议这类需求换框架^[1]。这条分界对建站选型的意义是：文档站要的是加载快与结构清楚，应用要的是状态管理，两者的默认取舍方向相反。

多语言文档属于另一件事。主题层能做语言切换的界面，版本之间的关系仍要配 hreflang 与规范网址^[3]，生成器不会替你决定哪个版本代表哪组页面。

常见误用

第一种是把源码目录与构建产物一起上传，文件数翻倍，旧稿页面也能被访问。第二种是文档站只依赖站内搜索，站点地图与目录页都不做，抓取入口只剩首页。第三种是改过文件名或层级后不处理旧地址，历史收录失去落点^[3]。

附录

参见

• 静态站点生成器
• Hugo
• Hexo
• Astro
• Jekyll
• Nginx 缓存
• hreflang

参考资料

官方（境外）

1. 《What is VitePress?》，VitePress 文档。
2. 《Deploying VitePress》，VitePress 文档。
3. 《规范网址与重复内容的处理》，Google 搜索中心。

外部链接

• VitePress 主题配置参考，VitePress 文档。