开发与发布指南

本地验证

安装依赖后运行：

bash

npm test

测试会先执行 VitePress 生产构建，再检查源码配置和构建产物中的站点基址。

Claude Code 教程的公开地址是：

text

https://xueai.me/library/claude-code/

.vitepress/config.mts 中的 base 必须保持为：

text

/library/claude-code/

生产构建产物位于 .vitepress/dist，由仓库根目录下的 website/deploy-library.py 上传到服务器。Nginx 的文章库配置必须从 deploy/nginx-library.conf 模板生成，不能只修改服务器实例。

现象：服务器请求返回 200，HTML 中也有正文，但浏览器执行 VitePress 客户端脚本后显示 PAGE NOT FOUND。

根因：VitePress 的 base 曾被配置为 /v2/library/claude-code/，而公开入口和 Nginx 部署路径是 /library/claude-code/。客户端路由无法把当前地址映射到构建页面，因此在加载后切换为 404。

解法：把 base 恢复为 /library/claude-code/，重新执行 npm test 生成构建产物，再运行 python ../../website/deploy-library.py。

防范：保留 tests/base-path.test.mjs。部署前必须运行 npm test，不能只检查 HTTP 状态码，因为状态码检查发现不了客户端路由 404。

现象：服务器已经返回新基址，带随机查询参数的地址也能正常打开，但访问原地址仍可能显示部署前的 404。刷新后恢复。

根因：HTML 响应没有禁止缓存。浏览器继续复用部署前的 VitePress HTML 和客户端脚本，其中仍带有旧 /v2/library/claude-code/ 基址。

解法：使用 deploy/nginx-library.conf。教程 HTML 和文章库动态入口返回 Cache-Control: no-cache, no-store, must-revalidate，带内容哈希的资源文件长期缓存，缺失资源直接返回 404。

防范：保留 tests/deployment-cache.test.mjs。部署验收必须同时检查响应头、原始地址的真实浏览器渲染和一个 clean URL 子页面。

现象：页面正文能够打开，但字体、布局和颜色全部退化为浏览器默认样式。Nginx 访问日志同时出现教程 CSS 和 JavaScript 文件 404，部署结束后刷新又恢复。

根因：旧部署流程先把线上目录移动到备份，再通过 SFTP 逐个上传新构建。入口 HTML 会先于 assets 目录完成上传，导致它在几分钟内引用尚不存在的哈希资源。立即移走上一版资源还会让已经打开的旧页面在延迟加载时继续请求 404。

解法：website/deploy-library.py 先把完整构建上传到独立版本目录，同时复制当前版本和最近备份中的哈希资源。上传与资源校验结束后，再通过版本符号链接切换线上目录。后续发布使用 mv -Tf 原子替换链接。

防范：保留 tests/atomic-deployment.test.mjs。发布完成后的公网检查必须读取入口 HTML，并逐一验证它引用的 CSS 和 JavaScript 状态码与内容类型。

现象：教程顶部只有章节导航。左上角标题只能回到教程首页，用户无法从教程返回 xueai.me 主站。

根因：VitePress 的 themeConfig.nav 没有主站入口。教程部署在子路径下，使用普通内部链接 / 还会被 VitePress 解释为教程根路径。

解法：在顶部导航添加“学AI主页”，使用完整地址 https://xueai.me/，并设置 target: '_self' 在当前标签页返回主站。

防范：保留 tests/home-navigation.test.mjs，同时检查源码配置和生产构建中的链接文本、地址及打开目标。