返回实战列表
部署 18 分钟阅读

部署到 Cloudflare Pages

把站点部署到 Cloudflare Pages，并梳理构建命令、环境变量、预览环境、回滚与常见部署故障。

C
ClawList Team
· 发布于 2025-03-12 · 更新于 2026-03-24

什么时候适合用 Cloudflare Pages？

如果你的项目是静态站点或以静态输出为主的前端应用，Cloudflare Pages 通常是一个非常省心的部署选择。它的优势不只是 CDN，而是把这些事情打包好了：

  • Git 驱动的自动部署
  • PR / 分支预览环境
  • 全球边缘分发
  • HTTPS 与回滚能力
  • 和 Cloudflare 生态其他服务的衔接

但也要注意：如果你的应用依赖复杂后端、长连接、重计算或大量私有网络访问，Pages 可能不是唯一答案。

开始前先确认这几件事

在接入 Cloudflare Pages 前，先明确：

  • 你的项目是否能稳定输出静态构建产物
  • 构建命令是否已经在本地验证过
  • 哪些变量属于公开配置，哪些属于 secret
  • Preview 与 Production 是否需要不同环境变量
  • 如果部署失败，团队如何定位问题

这一步做清楚，后面排查会省很多时间。

一个现实的部署流程

第一步：先在本地把构建跑通

不要先点 Dashboard，再回头猜构建命令。先在本地确认：

pnpm install
pnpm build

你至少需要知道：

  • 最终产物目录是什么
  • 构建过程依赖哪些环境变量
  • 是否存在构建后步骤（例如索引、压缩、静态搜索生成）

第二步：连接 Git 仓库

Cloudflare Pages 的常规流程通常是：

1. 登录 Cloudflare Dashboard

2. 进入 Workers & Pages

3. 选择创建 Pages 项目

4. 连接 GitHub 仓库

5. 选择要自动部署的分支

这里最重要的不是点按钮，而是想清楚：

  • 哪个分支代表 production
  • 是否为 feature branch 开 preview
  • 谁能触发生产部署

构建配置要如何理解？

无论你在 Dashboard 填写还是使用配置文件，核心都绕不开三件事：

  • 构建命令
  • 输出目录
  • 环境变量

下面是一个示意配置，用于解释常见配置项，不应被视为你项目的唯一正确 wrangler.toml 模板：

name = "my-site"
compatibility_date = "2026-03-01"

[build]
command = "pnpm build"

[site]
bucket = "./dist"

真正部署时，请以你的构建系统和 Cloudflare 当前支持的配置方式为准。

环境变量怎么分层？

这是部署里最容易出问题的部分之一。

至少把变量分成两类：

公开构建配置

例如：

  • 公开 API endpoint
  • feature flag
  • analytics id

敏感变量

例如：

  • LLM API keys
  • 数据库连接串
  • 私有服务 token

原则很简单：

  • 能放 secret 的，不要硬编码
  • Preview 和 Production 尽量分开管理
  • 本地 .env、CI secret、Cloudflare secret 要保持语义一致

Preview 环境为什么值得开？

很多部署问题只有在真实构建环境里才会暴露，例如：

  • 生产环境变量缺失
  • 路由规则与本地开发环境不一致
  • 静态资源路径在 preview 域名下出错
  • 第三方服务对域名或回调地址敏感

如果团队会频繁改前端、文案、配置或 SEO，开 preview 环境几乎是必需的。

CI/CD 应该关注什么？

关键不是“有没有 GitHub Actions”，而是部署链路是否清楚：

  • push 到哪个分支会触发生产部署
  • Pull Request 是否触发 preview
  • 部署前是否要先跑 lint / typecheck / build
  • 部署失败是否有明确日志入口

一个常见流程是：

1. PR 阶段跑校验

2. 生成 preview 供 review

3. 合并 main 后触发正式部署

4. 部署失败时保留回滚路径

常见故障排查思路

1. 本地能 build，云上不能 build

优先检查：

  • Node.js 版本差异
  • 包管理器锁文件是否一致
  • 某些环境变量是否只在本地存在
  • 构建脚本里是否依赖本机文件或本机路径

2. 部署成功，但页面是错的

优先检查：

  • 输出目录是否填错
  • 静态资源基础路径是否正确
  • SSR / SPA / 静态导出模式是否和站点配置匹配
  • redirect / rewrite 是否覆盖了你的页面路由

3. Preview 正常，Production 异常

优先检查：

  • 生产环境变量是否缺少
  • 域名绑定是否生效
  • 第三方服务是否只白名单了 preview 域名
  • 缓存是否命中了旧版本

一个更实用的验收清单

在你说“部署好了”之前，建议逐项确认：

  • [ ] 本地构建已验证
  • [ ] Cloudflare 构建命令与输出目录正确
  • [ ] Preview / Production 变量分层清楚
  • [ ] 生产域名访问正常
  • [ ] 至少知道如何看部署日志与回滚
  • [ ] 静态资源、路由、SEO 基本正常

下一步读什么？