用 Cloudflare Pages 自动部署 GitHub 私有仓库
如果一个网站项目保存在 GitHub 私有仓库中，可以通过 Cloudflare Pages 的 Git 集成完成部署。配置完成以后，每次向生产分支推送代码，Cloudflare 都会自动拉取最新提交、执行构建并更新网站。
最终工作流如下：
本地修改网站
↓ git commit
Git 提交
↓ git push origin main
GitHub 私有仓库
↓ 自动触发
Cloudflare Pages 构建与部署
↓
pages.dev 地址或自定义域名创建方式
创建 Pages 项目时需要选择“连接到 Git”，不要选择 Direct Upload。Git 集成才会监听 GitHub 的 push 并自动部署。
一、授权 Cloudflare 访问私有仓库
在 Cloudflare 控制台进入 Workers 和 Pages → 创建 → Pages → 连接到 Git，选择 GitHub。
第一次连接时，GitHub 会要求安装或配置 Cloudflare Workers and Pages 应用。私有仓库不会自动对所有第三方应用开放，需要在 GitHub 授权页面中选择：
All repositories：允许 Cloudflare 访问该账号下的所有仓库。Only select repositories：只授权准备部署的私有仓库，更适合权限最小化。
如果在 Cloudflare 的仓库列表中找不到目标仓库，可打开 GitHub Applications，找到 Cloudflare Workers and Pages，点击 Configure，再把目标仓库加入 Repository access。
Note
GitHub 仓库仍然是私有的。这里授予的是 Cloudflare 构建服务读取仓库的权限，不会把仓库源码公开；网站构建产物会被公开访问。
二、选择仓库与生产分支
选择私有仓库后进入构建设置页面，可以先填写：
| 配置项 | 示例 | 说明 |
|---|---|---|
| 项目名称 | my-private-site | 会生成 my-private-site.pages.dev，名称需要唯一 |
| 生产分支 | main | 推送到该分支会更新正式网站 |
| 框架预设 | 无 | 纯 HTML 网站选择“无”；框架项目按实际技术栈选择 |
其他分支默认可用于 Preview Deployment。向非生产分支推送或创建 Pull Request 时，Cloudflare 可以生成独立预览地址，而不会覆盖正式网站。
三、填写构建设置
构建命令和构建输出目录取决于仓库结构。最重要的原则是：构建输出目录必须指向最终可公开访问的静态文件所在目录。
情况 A：仓库根目录直接是静态网站
例如：
my-private-site/
├── index.html
├── styles.css
├── app.js
└── assets/推荐填写：
| 配置项 | 填写内容 |
|---|---|
| 框架预设 | 无 |
| 构建命令 | exit 0 |
| 构建输出目录 | / |
| 根目录（高级） | 留空 |
| 环境变量 | 不需要则留空 |
exit 0 表示没有额外构建步骤，并向 Cloudflare 返回成功状态。也可以将构建命令留空，但 Cloudflare 的静态 HTML 指南推荐在无框架项目中使用 exit 0。
情况 B：静态网站位于子目录
例如：
my-private-site/
├── README.md
└── website/
├── index.html
├── styles.css
└── assets/可填写：
| 配置项 | 填写内容 |
|---|---|
| 框架预设 | 无 |
| 构建命令 | exit 0 |
| 构建输出目录 | website |
| 根目录（高级） | 留空 |
也可以把根目录设置为 website，再将输出目录填写为 /。两种方式不要重复叠加，否则容易指向错误目录。
情况 C：使用 Vite、React、Vue 或 Astro
如果仓库需要先执行构建，通常填写：
| 技术栈 | 构建命令 | 构建输出目录 |
|---|---|---|
| React + Vite | npm run build | dist |
| Vue + Vite | npm run build | dist |
| Astro | npm run build | dist |
| Next.js 静态导出 | npx next build | out |
具体值仍应以项目自己的 package.json 和框架配置为准。如果本地执行 npm run build 后生成的目录不是表中名称，应填写项目实际生成的目录。
四、完成第一次部署
确认配置后点击 保存并部署。Cloudflare 会依次完成：
- 从 GitHub 私有仓库拉取代码。
- 安装项目依赖（如有）。
- 执行构建命令。
- 上传构建输出目录中的文件。
- 生成
项目名称.pages.dev地址。
第一次部署成功后，打开 Pages 地址检查首页、样式、图片和内部链接。
五、验证 push 后自动部署
在本地修改一个可见内容，然后提交并推送：
git status
git add .
git commit -m "更新网站内容"
git push origin main回到 Cloudflare Pages 项目的 部署 页面，应该能看到一条与最新 Git commit 对应的新部署记录。构建完成后，正式地址会自动切换到新版本。
Cloudflare 的 Git 集成默认会监听生产分支的提交；不需要另外创建 GitHub Actions，也不需要手动上传文件。
六、常见问题
首页显示 404
优先检查构建输出目录中是否有顶层 index.html：
构建输出目录/
└── index.html如果 index.html 实际位于更深的子目录，说明构建输出目录填写错了。
Cloudflare 找不到私有仓库
进入 GitHub Applications，检查 Cloudflare Workers and Pages 是否已获准访问该仓库。仓库属于 GitHub Organization 时，还需要组织所有者或 GitHub Apps Manager 授权。
GitHub 已经 push，但没有触发部署
依次检查：
- 推送的分支是否是 Pages 设置中的生产分支。
- Pages 项目的 设置 → 构建 → 分支控制 中，是否开启了自动生产分支部署。
- commit message 是否包含
[CI Skip]、[Skip CI]或[CF-Pages-Skip]。 - GitHub App 是否仍然拥有该仓库的访问权限。
构建成功，但网页缺少 CSS 或图片
检查资源路径是否依赖本地绝对路径，或是否错误地写成仅适用于开发服务器的地址。静态文件应进入构建输出目录，并使用部署后仍然有效的相对路径或站点路径。
私有仓库会泄露源码吗
Cloudflare Pages 公开的是构建输出目录，而不是整个 Git 仓库。但如果把源码、密钥、配置文件或内部文档复制进输出目录，它们仍会被公开。因此：
- 不要把 Token、密码或私钥提交到 Git。
- 敏感配置使用 Cloudflare 环境变量。
- 发布前检查构建输出目录中实际包含哪些文件。
七、后续绑定自定义域名
Pages 地址正常访问后，可以进入项目的 自定义域 页面添加域名。如果域名 DNS 已托管在 Cloudflare，系统通常可以自动创建所需记录；如果 DNS 在其他服务商，需要按页面提示添加 CNAME 记录。
建议先确保 pages.dev 地址和自动部署完全正常，再配置自定义域名，这样排查问题时可以把“网站构建”和“DNS 配置”分开处理。
参考资料
- Cloudflare Pages：Git integration
- Cloudflare Pages：GitHub integration
- Cloudflare Pages：Build configuration
- Cloudflare Pages：Static HTML
- Cloudflare Pages：Branch deployment controls
- Cloudflare Pages：Troubleshooting builds
这套配置完成后，日常发布只需要维护 GitHub 仓库：每次向 main 分支推送，Cloudflare Pages 就会自动构建并更新网站。