一次文档 404 是如何定位到同步副本链路的

静态文档站最容易出现的一类错觉是：页面是 Markdown 写的，所以只要文件存在，页面就应该存在。

但当前项目不是“直接渲染根目录文档”的结构，而是两段式：

• 根目录 docs/ 是唯一事实源
• site/docs/ 是给 VitePress 和 Docker 使用的同步副本

一旦有人把这个边界弄混，就很容易出现下面这些问题：

• 首页 404
• 某个文档页 404
• 开发模式返回异常内容
• Docker 吃到旧副本

为什么会这样

因为 VitePress 当前实际消费的是 site/docs/，不是根目录 docs/。

如果你只改了根目录文档，但没有同步副本，运行站点时看到的就不是最新内容。

如果你把 site/docs 改成了不合适的链接形式，开发模式甚至可能连导入行为都不稳定。

当前项目最终采用的约束

• 根目录 docs/ 是唯一手工维护入口
• site/docs/ 只能由同步脚本生成
• 站点和 Docker 都只消费 site/ 里的内容

这个约束看起来多了一步，但它换来的是：

• 目录职责清晰
• 站点壳层可独立启动
• Docker 部署目录清晰
• 发布链路更可控