Cloudflare Pages 部署指南：选择 Git integration、Direct Upload 或 C3

Cloudflare Pages 适合把前端源代码或已经生成的静态产物发布到 Cloudflare。官方入门页提供 Git integration 和 Direct Upload 两种项目集成方式；C3 CLI 则帮助从零创建项目，并可选择立即部署。需要每次推送自动构建就选 Git integration；已经有稳定构建产物就选 Direct Upload。使用 C3 时，部署提示的选择决定后续能否连接 Git。

项目创建时就要确定集成方式。 Direct Upload 官方文档说明这种项目之后不能切换到 Git integration；Git integration 文档也说明反向不能直接切换。需要改变项目类型时应新建项目、重新验收预览与域名切换。已有 Git 集成项目可以关闭自动构建并用 Wrangler 手动部署，但这不是将它改成 Direct Upload 项目。

前置条件

一个 Cloudflare 账户。
Git integration 需要 GitHub 或 GitLab 仓库及可运行的构建命令。
Direct Upload 需要本地已经生成的静态输出目录。
C3 CLI 需要 Node.js 和可用的 Cloudflare 登录流程。
明确框架的构建命令和输出目录，例如 npm run build 与 dist；不同框架的目录可能是 build、out 或其他路径。

部署路径

Git integration

在 Cloudflare Dashboard 创建 Pages 项目并连接 GitHub 或 GitLab 仓库，选择生产分支，填写构建命令、输出目录和构建环境变量。之后每次推送都会触发新的构建。Pull Request 或分支预览适合在绑定生产域名前检查页面。

Direct Upload

本地执行项目的构建命令，确认输出目录只包含准备公开的静态文件，然后在 Pages 项目中选择 Direct Upload 上传该目录，或对这种项目运行 npx wrangler pages deploy <BUILD_OUTPUT_DIRECTORY>。这个模式不会自动读取源码仓库，构建和产物保存责任在执行上传的一方。打算以后连接 Git 自动构建时，应从一开始选择 Git integration。

C3 CLI

C3 适合从命令行创建新的 Pages 项目。先阅读 Pages C3 CLI 文档，在空目录运行：

npm create cloudflare@latest -- --platform=pages

确认生成的项目目录、构建命令和输出目录。在 Do you want to deploy your application? 提示选择 yes，会登录账户并立即部署为 Direct Upload 项目，之后不能连接 Git integration；成功时应能看到部署地址并检查页面与静态资源。如果计划让 GitHub/GitLab 推送触发构建，务必选择 no，然后创建 Git 仓库并按 Git integration 流程在 Dashboard 新建 Pages 项目；成功信号是项目关联目标仓库并出现对应提交的构建记录。C3 的源码生成和远程部署是两个可分开的动作，域名、环境变量和缓存策略仍需单独验收。

Mermaid 流程图

正在准备渲染...

查看源码

flowchart TD
    A[前端源代码] --> Q{已有项目或从零创建?}
    Q -->|已有项目，需要 Git 自动构建| G[Git integration]
    Q -->|已有构建产物| D[Direct Upload]
    Q -->|从零创建| C[C3 生成项目]
    C --> Y{立即部署?}
    Y -->|是| D
    Y -->|否，计划连接 Git| G
    G --> P[关联仓库与构建记录]
    D --> U[上传批次与预览地址]
    P --> V[域名和页面验收]
    U --> V

配置与绑定

Pages 的构建配置至少要记录：源码仓库、生产分支、构建命令、输出目录、Node.js 版本和构建环境变量。不要把 API Token、数据库密码或其他 Secret 写入仓库或普通环境变量；需要保密的值应使用 Pages 的 Secret 配置或受控 CI Secret。

Pages 静态部署本身不需要 KV、D1 或 R2 绑定。如果前端通过 Workers Functions、API 或其他后端访问这些资源，应把后端绑定和数据迁移写入独立的 Workers 部署文章，并说明跨环境的资源名称。

验收

文档级部署完成后，至少应检查：

Dashboard 中的构建记录状态为成功，并能看到对应提交或上传批次。
预览地址能够返回页面，静态资源路径没有 404。
SPA 项目刷新深层路由时不会错误回源；需要重写时记录实际配置。
绑定自定义域名后，DNS、HTTPS 证书、缓存和访问控制符合预期。
使用 curl -I https://<preview-or-domain> 检查响应状态和缓存相关响应头。

以上是验收清单，不代表本篇已经执行 Pages 构建或远程发布；当前文章验证等级为 documented。

回滚边界

Git integration 回滚应回到已知可用的提交或重新触发该提交的构建。
Direct Upload 必须保留每次上传对应的构建产物和版本说明，否则无法可靠重建旧版本。
切换 Git integration 与 Direct Upload 不是版本回滚；需要新建项目时，应先准备新项目的构建配置、Secret 和预览地址，再按流量切换计划处理自定义域名和旧项目。
自定义域名、DNS 和缓存配置与构建产物是两个边界；回滚页面版本不会自动回滚 DNS 或缓存策略。
如果页面依赖外部 API、Workers 或数据库，页面回滚不能自动恢复 API 代码和数据 schema，必须分别制定兼容和回滚顺序。

Cloudflare Pages 部署指南：选择 Git integration、Direct Upload 或 C3 ​

前置条件 ​

部署路径 ​

Git integration ​

Direct Upload ​

C3 CLI ​

配置与绑定 ​

验收 ​

回滚边界 ​

参考资料 ​