Back to Details

cloudflare-pages

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Cloudflare Pages

Cloudflare Pages

Deploy any static site to Cloudflare Pages — create projects, attach custom domains, wire up CI/CD, and verify deployments. Framework-agnostic: works with Hugo, Astro, Next.js, Nuxt, SvelteKit, or any build tool that produces static output.
将任意静态站点部署到Cloudflare Pages——创建项目、绑定自定义域名、配置CI/CD并验证部署。框架无关：支持Hugo、Astro、Next.js、Nuxt、SvelteKit或任何可生成静态输出的构建工具。

Prerequisites

前置条件

RequirementHow to get it
wrangler CLI
npm i -g wrangler
then 
wrangler login
(opens browser OAuth)
Cloudflare accountdash.cloudflare.com — free tier works
Account IDDashboard → any zone → Overview sidebar, or 
wrangler whoami
API Token (CI/CD)Dashboard → API Tokens → "Edit Cloudflare Workers" template (includes Pages)
DNS API TokenDashboard → API Tokens → Custom → Zone:DNS:Edit (only if adding custom domains via API)
Zone IDDashboard → your domain → Overview sidebar (only for custom domains)
要求获取方式
wrangler CLI
npm i -g wrangler
后执行 
wrangler login
（打开浏览器OAuth验证）
Cloudflare 账号dash.cloudflare.com — 免费套餐可用
账号ID控制台 → 任意区域 → 侧边栏概览，或执行 
wrangler whoami
API Token（CI/CD用）控制台 → API Tokens → “Edit Cloudflare Workers” 模板（包含Pages权限）
DNS API Token控制台 → API Tokens → 自定义 → Zone:DNS:Edit（仅当通过API添加自定义域名时需要）
区域ID控制台 → 你的域名 → 侧边栏概览（仅自定义域名需要）

Quick Deploy

快速部署

For a one-off manual deploy when CI/CD isn't set up yet:
bash
undefined
当尚未配置CI/CD时，可使用以下一次性手动部署方式：
bash
undefined

1. Build your site

1. 构建你的站点

<your-build-command> # e.g. hugo --minify, npm run build
<your-build-command> # 例如 hugo --minify, npm run build

2. Deploy output directory

2. 部署输出目录

wrangler pages deploy <output-dir> --project-name <project-name>

Each deploy gets a unique preview URL. The latest deploy on `production` branch becomes the live site at `<project>.pages.dev`.
wrangler pages deploy <output-dir> --project-name <project-name>

每次部署都会生成唯一的预览URL。`production`分支上的最新部署会成为`<project>.pages.dev`上的正式站点。

Full Setup Workflow

完整设置流程

Step 1 — Create the Pages project

步骤1 — 创建Pages项目

bash
bash scripts/setup_pages_project.sh <project-name> "<build-command>" <output-dir> [branch]
This runs 
wrangler pages project create
and prints the resulting 
*.pages.dev
URL. The 
branch
argument defaults to 
main
.
Manual alternative:
bash
wrangler pages project create <project-name> --production-branch main
bash
bash scripts/setup_pages_project.sh <project-name> "<build-command>" <output-dir> [branch]
该脚本会执行
wrangler pages project create
并输出生成的
*.pages.dev
URL。
branch
参数默认值为
main
。
手动替代方案：
bash
wrangler pages project create <project-name> --production-branch main

Step 2 — Deploy

步骤2 — 部署

Build and deploy:
bash
<your-build-command>
wrangler pages deploy <output-dir> --project-name <project-name>
构建并部署：
bash
<your-build-command>
wrangler pages deploy <output-dir> --project-name <project-name>

Step 3 — Add a custom domain

步骤3 — 添加自定义域名

bash
undefined
bash
undefined

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>

The script performs two operations:
1. **Registers** the domain on the Pages project via Cloudflare API
2. **Creates** a proxied CNAME DNS record pointing to `<project>.pages.dev`

Both operations are idempotent — safe to re-run.
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>" # 可选，若未设置则回退使用API_TOKEN
bash scripts/add_custom_domain.sh <custom-domain> <project-name>

该脚本执行两项操作：
1. **注册**：通过Cloudflare API将域名绑定到Pages项目
2. **创建**：指向`<project>.pages.dev`的代理CNAME DNS记录

两项操作均为幂等操作——可安全重复执行。

Step 4 — Set up CI/CD

步骤4 — 配置CI/CD

See references/ci-cd-templates.md for complete GitHub Actions workflows for Hugo, Astro, Next.js, and generic npm builds.
Required GitHub Secrets:
SecretValue
CLOUDFLARE_API_TOKEN
API token with "Edit Cloudflare Workers" permissions
CLOUDFLARE_ACCOUNT_ID
Your Cloudflare account ID
Set these at: Repository → Settings → Secrets and variables → Actions → New repository secret
查看**references/ci-cd-templates.md** 获取适用于Hugo、Astro、Next.js和通用npm构建的完整GitHub Actions工作流。
必需的GitHub Secrets：
密钥值
CLOUDFLARE_API_TOKEN
拥有“Edit Cloudflare Workers”权限的API令牌
CLOUDFLARE_ACCOUNT_ID
你的Cloudflare账号ID
在以下路径设置：仓库 → 设置 → 机密与变量 → Actions → 新建仓库机密

Rollback

回滚部署

bash
undefined
bash
undefined

List recent deployments

列出最近的部署记录

wrangler pages deployment list --project-name <project-name>
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>
git checkout <commit-hash> <your-build-command> wrangler pages deploy <output-dir> --project-name <project-name>

Return to latest

回到最新版本

git checkout main
undefined
git checkout main
undefined

Verify Deployment

验证部署

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

bash scripts/verify_deployment.sh <project-name> [custom-domain]
Shows: latest deployment status (color-coded), last 5 deployments table, custom domain SSL status, and HTTP 200 check on 
*.pages.dev
.
bash
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检查结果。

Script Reference

脚本参考

ScriptPurposeRequired env vars
setup_pages_project.sh
Create Pages project via wrangler
CLOUDFLARE_ACCOUNT_ID
add_custom_domain.sh
Register domain + create CNAME
CLOUDFLARE_ACCOUNT_ID
, 
CLOUDFLARE_API_TOKEN
, 
CLOUDFLARE_ZONE_ID
verify_deployment.sh
Check deploy status, SSL, HTTP
CLOUDFLARE_ACCOUNT_ID
, 
CLOUDFLARE_API_TOKEN
脚本用途必需的环境变量
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 Reference

令牌参考

OperationToken neededScopeWhere used
wrangler pages deploy
Wrangler OAuthAutomatic via 
wrangler login
Local CLI, CI/CD
Register custom domain on PagesAPI TokenAccount:Cloudflare Pages:Edit
add_custom_domain.sh
Create CNAME DNS recordDNS API TokenZone:DNS:Edit
add_custom_domain.sh
CI/CD deploy (GitHub Actions)API Token"Edit Cloudflare Workers" templateGitHub Secrets
Query deploymentsAPI TokenAccount:Cloudflare Pages:Read
verify_deployment.sh
Tip: For simpler setups, a single API token with both Pages:Edit and DNS:Edit scopes can be used — set 
CLOUDFLARE_API_TOKEN
and omit 
CLOUDFLARE_DNS_TOKEN
.
操作需要的令牌权限范围使用场景
wrangler pages deploy
Wrangler OAuth自动通过
wrangler login
获取		本地CLI、CI/CD
在Pages上注册自定义域名API TokenAccount:Cloudflare Pages:Edit
add_custom_domain.sh
创建CNAME DNS记录DNS API TokenZone:DNS:Edit
add_custom_domain.sh
CI/CD部署（GitHub Actions）API Token“Edit Cloudflare Workers”模板GitHub Secrets
查询部署记录API TokenAccount:Cloudflare Pages:Read
verify_deployment.sh
提示： 对于更简单的设置，可使用同时拥有Pages:Edit和DNS:Edit权限的单个API令牌——设置
CLOUDFLARE_API_TOKEN
并省略
CLOUDFLARE_DNS_TOKEN
即可。

Troubleshooting

故障排除

ProblemCauseFix
wrangler: command not found
wrangler not installed
npm i -g wrangler
Authentication error
OAuth expired or wrong token
wrangler login
(re-authenticate)
Custom domain stuck "pending"Missing or wrong CNAME recordCheck DNS: CNAME must point to 
<project>.pages.dev
SSL not provisioningDomain not proxied through CloudflareSet CNAME proxy to "Proxied" (orange cloud)
522 error on custom domainDNS record exists but wrong targetDelete old record, re-run 
add_custom_domain.sh
Deploy succeeds but site 404sWrong output directoryVerify build output dir matches deploy path
CI/CD deploy failsMissing GitHub secretsAdd 
CLOUDFLARE_API_TOKEN
and 
CLOUDFLARE_ACCOUNT_ID
问题原因解决方法
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 Secrets添加
CLOUDFLARE_API_TOKEN
和
CLOUDFLARE_ACCOUNT_ID

Anti-Patterns

反模式

  • Don't use Cloudflare's git integration — use 
    wrangler pages deploy
    for direct uploads. Git integration adds complexity with no benefit for this workflow.
  • Don't create multiple projects for the same site — one project can have multiple custom domains.
  • Don't skip the CNAME step — registering a domain on Pages without the DNS record leaves it "pending" indefinitely.
  • Don't use unproxied CNAME records — Cloudflare's SSL and CDN only work when the orange cloud (proxy) is enabled.
  • Don't hardcode account IDs in scripts — always use environment variables.
  • 不要使用Cloudflare的Git集成 —— 使用
    wrangler pages deploy
    进行直接上传。Git集成会增加复杂度，且在此工作流中无额外收益。
  • 不要为同一站点创建多个项目 —— 一个项目可绑定多个自定义域名。
  • 不要跳过CNAME步骤 —— 仅在Pages上注册域名而不添加DNS记录会导致状态一直停留在“pending”。
  • 不要使用未代理的CNAME记录 —— 只有启用橙色云朵（代理）时，Cloudflare的SSL和CDN才能正常工作。
  • 不要在脚本中硬编码账号ID —— 始终使用环境变量。