cloudflare-pages

Cloudflare Pages

将任意静态网站部署到 Cloudflare Pages — 创建项目、绑定自定义域名、接入 CI/CD，并验证部署。与框架无关：适用于 Hugo、Astro、Next.js、Nuxt、SvelteKit，或任何可生成静态输出的构建工具。

前置条件

要求	获取方式
wrangler CLI	运行 npm i -g wrangler，然后运行 wrangler login（会打开浏览器进行 OAuth）
Cloudflare 账户	dash.cloudflare.com — 免费套餐即可使用
Account ID	控制面板 → 任意区域 → 概览侧栏，或运行 wrangler whoami
API Token（CI/CD）	控制面板 → API Tokens → “Edit Cloudflare Workers” 模板（包含 Pages）
DNS API Token	控制面板 → API Tokens → Custom → Zone:DNS:Edit（仅在通过 API 添加自定义域名时需要）
Zone ID	控制面板 → 你的域名 → 概览侧栏（仅自定义域名需要）

快速部署

如果尚未设置 CI/CD，可进行一次手动部署：

# 1. Build your site
<your-build-command>          # e.g. hugo --minify, npm run build

# 2. Deploy output directory
wrangler pages deploy <output-dir> --project-name <project-name>

每次部署都会获得一个唯一的预览 URL。production 分支上的最新部署会成为 <project>.pages.dev 上的线上网站。

完整设置工作流

步骤 1 — 创建 Pages 项目

bash scripts/setup-pages-project.sh <project-name> "<build-command>" <output-dir> [branch]

此操作会运行 wrangler pages project create 并输出生成的 *.pages.dev URL。branch 参数默认为 main。

手动替代方式：

wrangler pages project create <project-name> --production-branch main

步骤 2 — 部署

构建并部署：

<your-build-command>
wrangler pages deploy <output-dir> --project-name <project-name>

步骤 3 — 添加自定义域名

# Set required environment variables
export CLOUDFLARE_ACCOUNT_ID="<your-account-id>"
export CLOUDFLARE_API_TOKEN="<pages-edit-token>"
export CLOUDFLARE_ZONE_ID="<your-zone-id>"
export CLOUDFLARE_DNS_TOKEN="<dns-edit-token>"   # optional, falls back to API_TOKEN

bash scripts/add-custom-domain.sh <custom-domain> <project-name>

该脚本会执行两项操作：

1. 通过 Cloudflare API 在 Pages 项目上注册域名
2. 创建一条代理 CNAME DNS 记录，指向 <project>.pages.dev

这两项操作均支持幂等，可安全地重复运行。

步骤 4 — 设置 CI/CD

完整的 GitHub Actions 工作流（适用于 Hugo、Astro、Next.js 和通用 npm 构建）请参阅 references/ci-cd-templates.md。

所需的 GitHub Secrets：

Secret	值
CLOUDFLARE_API_TOKEN	具有 “Edit Cloudflare Workers” 权限的 API token
CLOUDFLARE_ACCOUNT_ID	你的 Cloudflare Account ID

在此处设置：Repository → Settings → Secrets and variables → Actions → New repository secret

回滚

# List recent deployments
wrangler pages deployment list --project-name <project-name>

# Rollback: checkout previous commit, rebuild, redeploy
git checkout <commit-hash>
<your-build-command>
wrangler pages deploy <output-dir> --project-name <project-name>

# Return to latest
git checkout main

验证部署

export CLOUDFLARE_ACCOUNT_ID="<your-account-id>"
export CLOUDFLARE_API_TOKEN="<your-token>"

bash scripts/verify-deployment.sh <project-name> [custom-domain]

显示：最新部署状态（以颜色标示）、最近 5 次部署的表格、自定义域名 SSL 状态，以及对 *.pages.dev 的 HTTP 200 检查。

脚本参考

脚本	用途	所需环境变量
setup-pages-project.sh	通过 wrangler 创建 Pages 项目	CLOUDFLARE_ACCOUNT_ID
add-custom-domain.sh	注册域名 + 创建 CNAME	CLOUDFLARE_ACCOUNT_ID、CLOUDFLARE_API_TOKEN、CLOUDFLARE_ZONE_ID
verify-deployment.sh	检查部署状态、SSL、HTTP	CLOUDFLARE_ACCOUNT_ID、CLOUDFLARE_API_TOKEN

Token 参考

操作	所需 Token	范围	使用位置
wrangler pages deploy	Wrangler OAuth	通过 wrangler login 自动完成	本地 CLI、CI/CD
在 Pages 上注册自定义域名	API Token	Account:Cloudflare Pages:Edit	add-custom-domain.sh
创建 CNAME DNS 记录	DNS API Token	Zone:DNS:Edit	add-custom-domain.sh
CI/CD 部署（GitHub Actions）	API Token	“Edit Cloudflare Workers” 模板	GitHub Secrets
查询部署	API Token	Account:Cloudflare Pages:Read	verify-deployment.sh

提示： 对于较简单的设置，可使用同时具有 Pages:Edit 和 DNS:Edit 范围的单个 API token — 设置 CLOUDFLARE_API_TOKEN，并省略 CLOUDFLARE_DNS_TOKEN。

故障排查

问题	原因	解决方法
wrangler: command not found	未安装 wrangler	npm i -g wrangler
Authentication error	OAuth 已过期或令牌错误	wrangler login（重新进行身份验证）
自定义域名一直处于“pending”状态	CNAME 记录缺失或错误	检查 DNS：CNAME 必须指向 <project>.pages.dev
SSL 未能配置	域名未通过 Cloudflare 代理	将 CNAME 代理设置为“Proxied”（橙色云朵）
自定义域名出现 522 错误	DNS 记录存在，但目标地址错误	删除旧记录，重新运行 add-custom-domain.sh
部署成功，但网站返回 404	输出目录错误	确认构建输出目录与部署路径一致
CI/CD 部署失败	缺少 GitHub 密钥	添加 CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_ACCOUNT_ID

Agent 式工作流与氛围编程

• 迭代式部署： 不要指望首次运行就能获得完美的 CI/CD 配置或完成 DNS 传播。先起草配置或手动部署，查看 Cloudflare Pages 日志或状态检查，找出具体的构建错误或代理问题；每次只调整一项设置，然后重新部署，直到网站上线。
• 氛围编程： 在真实仓库中测试之前，先在本地提交可用的部署脚本和 GitHub Actions 工作流，以便在流水线出问题时轻松回滚。

反模式

• 不要使用 Cloudflare 的 Git 集成——使用 wrangler pages deploy 直接上传。Git 集成会让此工作流变得复杂，却没有任何好处。
• 不要为同一个网站创建多个项目——一个项目可以配置多个自定义域名。
• 不要跳过 CNAME 步骤——在 Pages 上注册域名但不添加 DNS 记录，会导致其无限期处于“pending”状态。
• 不要使用未启用代理的 CNAME 记录——只有启用橙色云朵（代理），Cloudflare 的 SSL 和 CDN 才能正常工作。
• 不要在脚本中硬编码账户 ID——始终使用环境变量。