发布文档站

Fast.Docs 使用 VitePress 生成每个页面自己的 HTML、CSS 和 JavaScript。部署目录是 docs/.vitepress/dist，不是源码目录，也不是只上传根 index.html。

构建与本地预览

bash

pnpm install --frozen-lockfile
pnpm run build
pnpm run preview

浏览器直接打开 http://localhost:4173/zh-CN/frontend/utils/runtime-contract，然后刷新。除了从首页点击进入，也应验证独立打开页面。

Nginx

仓库的 deploy/nginx.conf 提供完整 server 示例。在当前站点的 server 中合并其中的路由和缓存配置，保留自己的 root、端口、TLS 和日志设置。不要为同一域名重复创建 server。

root 必须指向完整的构建产物；Nginx 的 http 块应已加载 mime.types，保证 JavaScript 和 CSS 使用正确 MIME 类型。

核心路由：

nginx

location / {
    try_files $uri $uri.html $uri/ =404;
    add_header Cache-Control "no-cache" always;
}

location ^~ /assets/ {
    try_files $uri =404;
    add_header Cache-Control "public, max-age=31536000, immutable";
}

location = /hashmap.json {
    try_files $uri =404;
    add_header Cache-Control "no-cache" always;
}

/zh-CN/frontend/utils/runtime-contract 应读取 zh-CN/frontend/utils/runtime-contract.html；/zh-CN/ 应读取目录中的 index.html。不存在的页面和资源返回 404。

不要写成 try_files $uri $uri/ /index.html，也不要把所有 404 改成根首页。 普通 Vue SPA 的首页兜底会让深层 URL 收到错误页面的 HTML；VitePress 的页面数据、预渲染内容与客户端路由因此不匹配。

配置修改后先运行 nginx -t；只有校验成功，再执行 nginx -s reload。这些操作由部署人员执行，源码构建不会修改服务器。

上传与缓存

完整发布同一次构建中的 HTML、assets/、hashmap.json 及其他静态文件。HTML 和 hashmap.json 不采用长期不可变缓存；带哈希的资源可以长期缓存。使用 CDN 时同步检查其缓存和回源规则，不要在边缘把缺失 JS 改写为 HTML。

不要通过 CDN 的额外 HTML 压缩删除 Vue 的注释节点。替换线上产物后清理旧 HTML 和 hashmap.json 缓存，避免旧页面引用已经不存在的资源。

部署后验证

bash

pnpm run check:deployment -- http://docs.fastdotnet.cn/

检查器只发送读取请求，不写入服务。它验证中英文页面的直达 HTML 身份、重复请求、脚本和样式 MIME，以及不存在的页面和资源是否返回 404。需先发布本次构建产物，才能使用其中的 fast-docs-page 元数据核对页面身份。

浏览器再检查一次页面刷新和导航，并查看 Console 与 Network。返回 200 本身不能证明页面正确；若响应中是首页内容，或 .js 请求返回 text/html，应继续检查服务器/CDN 重写和发布文件是否一致。

其他静态托管

安装命令为 pnpm install --frozen-lockfile，构建命令为 pnpm run build，发布目录为 docs/.vitepress/dist。启用 cleanUrls: true 时，托管服务也必须将无扩展名 URL 映射到对应 .html，不使用 SPA 首页兜底。

独立域名使用默认根路径。部署到子目录时通过 pnpm run build --base /docs/ 指定路径，同时调整静态服务的目录映射。

发布文档站 ​

构建与本地预览 ​

Nginx ​

上传与缓存 ​

部署后验证 ​