前置说明
本文记录 Cloudflare Pages 项目从创建、连接 GitHub 仓库、配置构建命令，到自定义域名和访问统计配置的完整流程。
- 示例项目名为
blog，实际使用时可替换为自己的 Pages 项目名。 - 示例中的账号、邮箱、Account ID、Token 等环境相关信息统一使用占位符。
- 构建产物目录以
dist为例，适用于常见前端项目的npm run build输出。
创建 Cloudflare Pages 项目
打开 Pages 控制台
打开 Cloudflare Pages 控制台。
创建 Pages 项目
在 Pages 页面选择创建项目。
选择连接 GitHub。
选择连接特定仓库。
完成 GitHub 授权
根据 GitHub 二级验证提示完成授权。
查看首次部署状态
Cloudflare Pages 开始部署项目。
如果部署失败，进入构建配置和日志页面定位原因。
配置构建与部署命令
首次失败的原因是把 Cloudflare Pages 项目按 Workers 部署，需要改为 Pages 构建配置。
Build command: npm run build
Build output directory: dist
Root directory: /
Deploy command: npx wrangler pages deploy dist --project-name blog
保存配置后重新部署。
点击 Retry build 重新构建。
如果仍然失败，继续查看构建日志。
部署失败排查
API Token 权限不足
现象：Wrangler 调用 Cloudflare API 时返回 Authentication error [code: 10000]。
12:20:22.654
⛅️ wrangler 4.98.0
───────────────────
12:20:23.050
✘ [ERROR] A request to the Cloudflare API (/accounts/<CLOUDFLARE_ACCOUNT_ID>/pages/projects/blog) failed.
Authentication error [code: 10000]
📎 It looks like you are authenticating Wrangler via a custom API token set in an environment variable.
Please ensure it has the correct permissions for this operation.
Getting User settings...
👋 You are logged in with an User API Token, associated with the email <CLOUDFLARE_ACCOUNT_EMAIL>.
ℹ️ The API Token is read from the CLOUDFLARE_API_TOKEN environment variable.
┌───────────────────────────────────────────────┬──────────────────────────────────┐
│ Account Name │ Account ID │
├───────────────────────────────────────────────┼──────────────────────────────────┤
│ <CLOUDFLARE_ACCOUNT_EMAIL>'s Account │ <CLOUDFLARE_ACCOUNT_ID> │
└───────────────────────────────────────────────┴──────────────────────────────────┘
Failed: error occurred while running deploy command
原因：CLOUDFLARE_API_TOKEN 对 Pages 项目没有足够权限。
解决方法：进入 Cloudflare API Tokens 页面，为当前 Token 增加 Account / Cloudflare Pages / Edit 权限。
确认更新权限。
更新权限后继续点击 Retry build。
Pages 项目不存在
现象：权限问题解决后，Wrangler 返回 Project not found。
12:40:34.337
Executing user deploy command: npx wrangler pages deploy dist --project-name blog
12:40:35.515
npm warn exec The following package was not found and will be installed: wrangler@4.98.0
12:40:44.150
⛅️ wrangler 4.98.0
───────────────────
12:40:45.197
▲ [WARNING] Warning: Your working directory is a git repo and has uncommitted changes
To silence this warning, pass in --commit-dirty=true
12:40:45.334
✘ [ERROR] A request to the Cloudflare API (/accounts/<CLOUDFLARE_ACCOUNT_ID>/pages/projects/blog) failed.
Project not found. The specified project name does not match any of your existing projects. [code: 8000007]
Failed: error occurred while running deploy command
原因：创建入口或项目类型不正确，当前账号下没有与 --project-name blog 匹配的 Pages 项目。
解决方法：从 Cloudflare Pages 入口重新创建 Pages 项目，并确保项目名和部署命令中的 --project-name 一致。
重新创建 Pages 项目并部署成功
从 Pages 入口创建项目
在 Cloudflare Pages 入口重新创建项目。
填写构建配置
构建配置填写如下。
Build command: npm run build
Build output directory: dist
Root directory: /
Deploy command: npx wrangler pages deploy dist --project-name blog
启动部署并验证成功
开始部署。
部署成功时间为 12:53:13.156。
部署完成后，可以在 Pages 项目页面查看部署结果。
配置自定义域名
进入 Pages 项目的自定义域名配置页面。
添加自定义域名。
填写需要绑定的域名。
确认自定义域名配置。
等待域名状态生效。
域名传播完成后即可通过自定义域名访问 Pages 项目。
配置访问统计
获取统计脚本
进入 Cloudflare Web Analytics 或访问统计功能页面。
获取 JavaScript 统计脚本后，手动注入项目的 index.html。
关闭主域名自动注入
如果只希望手动控制脚本注入，可以关闭主域名的自动注入。
查看统计面板
打开统计面板查看访问数据。
验证结果
- Pages 项目可以通过 GitHub 仓库构建并部署成功。
npm run build输出目录为dist，Wrangler 使用pages deploy部署到 Pages 项目。CLOUDFLARE_API_TOKEN已补充Account / Cloudflare Pages / Edit权限。- 自定义域名传播完成后可以访问 Pages 项目。
- Web Analytics 统计面板可以正常打开并查看访问统计。