主题
发布与部署
本站用 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:check | 0 退出码;生成物过期会列出过期文件 |
| 复现 CI 构建 | npm run docs:build | 产物在 docs/.vitepress/dist,含 404.html 与搜索索引 |
| 只校验结构 | npm run docs:lint | front-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 公开访问——仓库私有并不等于站点私有。要限制访问:
- Cloudflare Zero Trust → Access → Applications → Add an application → Self-hosted;
- 域名填 Pages 域名(或自定义域名),策略选「Allow」并限定邮箱域名、Google/GitHub 组或一次性 PIN;
- 保存后,未登录访问会被拦到 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. 相关入口
- 构建与校验脚本:scan-knowledge.mjs、lint-knowledge.mjs
- CI 定义:docs.yml
- 内容与 ID 规范:规范-内容与ID