发布前先准备好的信息
- GitHub 仓库已创建，默认分支明确为 main
- Cloudflare 账户和域名所在 Zone 已确认
- 项目本地可构建，且静态产物目录明确
- 需要的环境变量、联系入口和统计方案已有占位或真实值
- 正式子域名和 pages.dev 默认域名都已规划
纯静态站的标准发布顺序
这是资料中最推荐的默认路线，也是当前 x-web 工作空间的默认发布方式。
1
本地构建并确认导出产物
静态站在推送前先本地构建一次，确保 `npm run build` 能通过，并检查导出目录是否如预期生成。
npm install npm run build ls out
2
首次推送到 GitHub
项目代码推到独立仓库，避免把工作空间根目录直接绑成生产 Pages 项目。
git init git add . git commit -m "init project" git branch -M main git remote add origin <your-repo> git push -u origin main
3
在 Cloudflare Pages 绑定仓库
选择对应仓库，填写构建命令、输出目录、Node 版本，并保存环境变量。
- Build Command 常见为 `npm run build`
- Output Directory 对 Next.js 静态导出通常是 `out`
- Node 建议和本地保持一致
4
绑定自定义子域名并验证
Pages 首次发布后先验证 pages.dev 域名，再绑定正式子域名，最后同时检查两个地址。
- 先确认 pages.dev 返回 200
- 再确认自定义域名 DNS 已生效
- favicon、联系入口和主要链接也要一起检查
需要动态能力时怎么接 Worker
原始资料把这部分单独拆成前端 + Worker 和独立 API 两种。首版保留决定点，不展开所有控制台细节。
页面仍走 Pages，接口单独走 Worker
适合静态页面为主，只需补表单、校验、Webhook 或少量数据聚合。页面发布不受接口代码影响。
多个站共用独立 API
当你预计会有多个站点共用同一份数据或接口规则时，把 API 单独拆出会更稳，也更方便权限与 CORS 控制。
上线验收时一定要看的项目
| 检查项 | 为什么重要 | 建议验证方式 |
|---|---|---|
| pages.dev 可访问 | 证明 Pages 构建和托管本身正常 | 浏览器打开并确认 HTTP 200 |
| 正式域名可访问 | 证明 DNS 和自定义域名绑定已生效 | 浏览器或 curl 检查返回状态 |
| favicon 与静态资源正常 | 能快速发现导出遗漏 | 打开 /favicon.ico 或页面资源面板 |
| 联系入口有效 | 避免发布后 CTA 成为摆设 | 点击验证是否可用或至少有明确占位说明 |
| 统计可用 | 后续无法回看数据是常见返工点 | 检查 Web Analytics 和前端埋点是否触发 |
Next.js 静态导出排查
如果 `npm run build` 失败，或者构建后没有生成 `out/`，优先从这几项往回查。
- 检查 `next.config.mjs` 是否明确开启 `output: 'export'`，否则 Pages 端可能拿不到静态导出产物
- 本地构建完成后确认项目根目录下是否真的生成 `out/`，如果没有，先回看构建日志是否已提前报错
- 确认页面没有误用 API Route、SSR 依赖、`cookies()`、`headers()`、动态服务端函数等静态导出不支持的能力
- 如果用了 `next/image`，检查是否已做静态导出兼容处理，例如改用普通资源或确认 `unoptimized` 配置
- 如果页面需要动态数据，优先改成构建期写死内容、外部可公开请求，或把动态能力拆到 Worker / 独立 API