Skip to content

发布与部署 ​

本站用 VitePress 构建、托管在 Cloudflare Pages。GitHub Actions 只做质量门禁,不负责发布,避免同一次推送被构建两遍。

1. 站点拓扑 ​

text
git push origin main
      │
      ├─ GitHub Actions(.github/workflows/docs.yml)
      │     npm ci → docs:check → docs:build → artifact(仅排查用)
      │
      └─ Cloudflare Pages(监听同一仓库)
            npm run docs:build → docs/.vitepress/dist → CDN 分发

2. Cloudflare Pages 项目设置 ​

配置项值
连接方式Workers & Pages → Create → Pages → Connect to Git
仓库StefanSongCN/pmforge(私有仓库需安装 Cloudflare GitHub App 并授权该仓库)
生产分支main
框架预设VitePress(无此选项时选 None)
根目录/
构建命令npm run docs:build
输出目录docs/.vitepress/dist
环境变量NODE_VERSION=20

.nvmrc 里也是 20,但 Pages 的构建镜像对 NODE_VERSION 更敏感,显式设置一次即可。

3. 本地与线上的一致性 ​

场景命令期望
改文档时实时预览npm run docs:dev默认 http://localhost:5173,热更新
提交前自检npm run docs:check0 退出码;生成物过期会列出过期文件
复现 CI 构建npm run docs:build产物在 docs/.vitepress/dist,含 404.html 与搜索索引
只校验结构npm run docs:lintfront-matter、站内链接、代码引用

4. 预览、回滚与缓存 ​

  • PR 预览:Cloudflare Pages 会为每个 Pull Request 生成独立预览域名,合并前可先看效果。
  • 回滚:Pages → 项目 → Deployments,选中历史上任意一次部署点 Rollback,线上立即切回该版本。
  • 缓存:docs/public/_headers 给 assets/ 下带哈希的静态资源设长缓存,HTML 设 max-age=0 保证每次拿到最新入口;改 _headers 后需要一次成功部署才生效。
  • 域名:Pages → Custom domains 可绑定自有域名;sitemap.xml 与 robots.txt 里的 hostname 见 docs/.vitepress/config.mts 的 sitemap.hostname,换域名时一起改。

5. 访问控制 ​

站点默认可通过 *.pages.dev 公开访问——仓库私有并不等于站点私有。要限制访问:

  1. Cloudflare Zero Trust → Access → Applications → Add an application → Self-hosted;
  2. 域名填 Pages 域名(或自定义域名),策略选「Allow」并限定邮箱域名、Google/GitHub 组或一次性 PIN;
  3. 保存后,未登录访问会被拦到 Cloudflare 登录页。

6. 常见构建失败 ​

现象原因处理
vitepress: not found / Node 版本报错构建镜像 Node 过旧设 NODE_VERSION=20 后 Retry deployment
npm ci 失败package-lock.json 与 package.json 不一致本地 npm install 后提交锁文件
构建成功但页面 404输出目录填错必须是 docs/.vitepress/dist(不是 docs/dist)
站内链接 404链接写成了相对路径或漏了 .html 语义npm run docs:lint 会列出无法解析的链接
改了代码但索引没变忘记重新生成npm run docs:gen,或让 CI 的 docs:check 拦下来

7. 相关入口 ​