Cloudflare Pages 部署

Cloudflare Pages 是当前私有仓库阶段的主发布入口。推荐使用 Pages 的 Git 集成，让 Cloudflare 读取 GitHub 私有仓库并在 master 更新后构建；项目仓库不保存 Cloudflare API Token。

构建配置

优先使用 Pages 的 Git 集成。只需配置构建命令和产物目录，Cloudflare 会在构建成功后接管发布：

配置	值
Production branch	master
Framework preset	VitePress 或 None
Build command	npm run docs:build
Build output directory	docs/.vitepress/dist
Root directory	/
Node.js	22 或 Cloudflare 当前支持的更高 LTS

无需设置 SITE_BASE，Cloudflare Pages 默认从域名根路径提供站点。

如果当前 Cloudflare 项目使用带 Deploy command 的构建配置，请将该字段设置为：

npm run pages:deploy

这个脚本会先执行 VitePress 生产构建，再运行：

wrangler pages deploy docs/.vitepress/dist --project-name github-guides

不要使用 npx wrangler deploy。该命令面向 Cloudflare Workers；对当前 Pages 配置执行时，Wrangler 会提示应改用 wrangler pages deploy，随后因为没有 Worker 入口或 Workers 静态资源目录而失败。

本地 Pages 运行时验证

npm ci
npm run pages:dev

命令先执行生产构建，再通过本地 Wrangler 提供 docs/.vitepress/dist。默认地址是 http://localhost:8788。它不会登录 Cloudflare、创建项目或部署远端资源。

至少检查首页、指南索引、深层文章路径、部署文档、404 和移动端溢出。

生产发布边界

npm run pages:deploy 会直接上传到远端 Pages 项目，只能在明确发布时运行；本地验证仍使用 npm run pages:dev。

本地构建成功后仍需单独确认公开内容、提交/推送 Git、在 Cloudflare 创建或连接项目、设置正式域名。上述操作不属于本地验证，不由本地检查脚本自动执行。

常见故障

Missing entry-point to Worker script or to assets directory

如果日志同时包含下面的警告，说明 Cloudflare 运行了错误的部署命令：

It seems that you have run `wrangler deploy` on a Pages project,
`wrangler pages deploy` should be used instead.

处理步骤：

1. 确认项目类型仍是 Cloudflare Pages。
2. 将 Deploy command 从 npx wrangler deploy 改为 npm run pages:deploy。
3. 不要为了消除报错而向 wrangler.jsonc 添加 Worker main 或 assets；这会改变部署模型。
4. 重新部署后确认日志先出现 VitePress 构建成功，再出现 Pages 文件上传记录。

参考：Cloudflare Pages 和 VitePress 部署指南。