Cloudflare Pages 托管让前端团队能够发布快速、安全且无需服务器管理的代码。通过使用 Cloudflare Pages ，开发者获得了一个高性能的边缘原生平台，用于部署静态 Web 应用、单页应用（SPA）和服务端渲染（SSR）框架。通过直接连接到你的 Git 仓库，Cloudflare 自动化构建流水线、生成预览部署，并在全球范围内托管资源。本指南将说明如何连接 Git、配置构建设置、设置自定义域名以及配置重定向。

要点速览（TL;DR）

  • 部署边缘原生前端应用；Cloudflare Pages 从 Cloudflare 网络在全球范围内提供资源，确保亚秒级加载时间。
  • 自动化 Git 集成；关联你的仓库以触发自动构建，并为每次提交生成预览 URL。
  • 配置框架构建设置；为 React、Vue、Next.js、Hugo 或 Astro 设置输出目录和命令。
  • 使用 public 文件夹中的纯文本 _redirects 和 _headers 文件应用重定向和标头规则。
  • 使用由 Cloudflare 管理的免费、自动续期的 SSL 证书映射自定义域名。

什么是 Cloudflare Pages？

Cloudflare Pages 是一个面向前端开发者的无服务器托管平台，类似于 Netlify 或 Vercel，直接构建于 Cloudflare 的全球基础设施之上。

Cloudflare Pages 不是将文件托管在单个云服务器上，而是将你的 HTML、CSS、JavaScript 和图片分发到世界各地的边缘节点。当用户请求你的站点时，资源会从最近的位置提供，从而降低网络延迟。对于需要服务端逻辑的项目，Pages 会与 Cloudflare Workers 集成以运行后端函数。要将 Pages 与其他边缘计算服务进行比较，请阅读我们关于 Cloudflare Pages vs Workers 的指南。

先决条件

开始之前，请确保你已准备好以下各项：

  • 一个位于 GitHub 或 GitLab 上、包含你项目的 Git 仓库（或已构建好、可直接上传的文件）。
  • 一个输出静态资源的框架 —— React（Vite）、Vue、Astro、SvelteKit、Hugo 或纯 HTML。服务端渲染框架也可以通过 Pages Functions 运行。
  • 一个可正常工作的本地构建。 在连接任何东西之前，运行你的构建命令（例如 npm run build）并确认输出文件夹能够无错误地生成。
  • 一个免费的 Cloudflare 账户。 免费套餐无需信用卡。
  • 在本地安装 Node.js（推荐），以便你可以复现构建并使用 Wrangler 命令行工具。

一次快速的合理性检查能在日后节省数小时的调试时间：如果你的站点在自己的机器上无法干净地构建，那么它在 Cloudflare 的构建器上也无法构建。请先解决本地错误。

第 1 步：连接你的 Git 仓库

首先，登录 Cloudflare Dashboard，导航到 Compute > Pages，然后点击 Create a project。

选择 Connect to Git 以关联你的 GitHub 或 GitLab 账户。选择包含你静态 Web 应用的仓库。这种集成非常有价值，因为它建立了一条持续集成（CI）流水线：每次你将代码推送到生产分支时，Cloudflare 都会自动构建并部署更新。对于其他提交，Cloudflare 会生成唯一的“预览 URL”，以便你在合并之前测试更改。

第 2 步：配置构建设置

Cloudflare Pages 支持流行的静态站点生成器和前端框架。在设置向导过程中，根据你的技术栈配置以下设置：

  • 构建命令：在你的 package.json 中定义的构建脚本（例如 npm run build 或 hugo --minify）。
  • 构建输出目录：包含已编译静态文件的文件夹（例如 dist、build 或 public）。
  • 环境变量：如果你的构建脚本需要 API 密钥或配置变量，请在此处定义它们。

Cloudflare 会自动检测许多框架，但确认预设可以避免首次构建失败。常见的组合有：

框架构建命令输出目录
React (Vite)npm run builddist
React (Create React App)npm run buildbuild
Next.js (static export)npx next buildout
Astronpm run builddist
Vue (Vite)npm run builddist
SvelteKitnpm run build.svelte-kit/cloudflare
Hugohugo --minifypublic

固定你的 Node 版本。 “本地能用，Cloudflare 上失败”的一个常见原因是构建运行器默认使用的 Node 版本与你项目期望的版本不匹配。请显式声明它，可以作为 dashboard 中的环境变量：

1NODE_VERSION = 20

或者通过向仓库根目录提交一个 .node-version 文件：

120

第 3 步：设置重定向和标头

对于单页应用（如 React Router）或旧版 URL 迁移，你必须配置路由和重定向规则。Pages 通过放置在你输出目录中的简单文本文件来处理这一点。

重定向 (_redirects)

在你的 public 文件夹中创建一个名为 _redirects 的文件。为了让 React SPA 干净地处理客户端路由，请添加回退规则：

1/*  /index.html  200

这会强制所有请求解析到 index.html，从而允许 JavaScript 路由器管理路径。

顺序很重要。Cloudflare 从上到下评估规则并在第一次匹配时停止，因此具体的重定向必须位于通配回退之上：

1# Permanent redirect for a moved page
2/old-pricing   /pricing            301
3
4# Redirect an entire section, preserving the sub-path
5/blog/*        /articles/:splat    301
6
7# SPA fallback (must come last)
8/*             /index.html         200

:splat 占位符会将路径中匹配到的部分传递到目标地址。免费套餐允许每个项目最多 2,000 条静态重定向规则；超出该数量后，请将逻辑迁移到 Pages Function 或 Bulk Redirects 中。

自定义标头 (_headers)

创建一个名为 _headers 的文件，以应用安全规则、Referrer-Policy 或自定义缓存控制：

1/*
2  X-Frame-Options: DENY
3  X-Content-Type-Options: nosniff
4  Referrer-Policy: strict-origin-when-cross-origin

同一个文件也是调整缓存的合适位置。带指纹的不可变资源可以缓存一年，而 HTML 则保持新鲜，以便用户始终收到最新的构建：

1/assets/*
2  Cache-Control: public, max-age=31536000, immutable

要了解这些规则与传统后端路由的对比，请阅读使用 Cloudflare Workers 构建无服务器 API 。

第 4 步：映射自定义域名

部署完成后，Cloudflare 会提供一个默认子域名（例如 your-project.pages.dev）。

要映射你的自定义域名，请导航到 Pages 项目中的 Custom Domains 选项卡，并输入你的域名（例如 yourcompany.com）。如果你的 DNS 由 Cloudflare 管理，平台会配置 CNAME 记录并立即预配一个免费、自动续期的 SSL 证书。如果你在管理域名映射、DNS 或服务器安全方面需要帮助，请查看网站安全审计 页面。

第 5 步：使用 Wrangler CLI 部署（直接上传）

Git 集成适合大多数团队，但你也可以使用 Cloudflare 的命令行工具 Wrangler 直接从你的机器或现有流水线进行部署。当你的构建已经在 GitHub Actions 或 GitLab CI 中运行，而你只想上传已完成的输出时，这会很有用。

安装 Wrangler 并进行身份验证：

1npm install -g wrangler
2wrangler login

在本地构建，然后将输出目录推送到一个已命名的项目：

1npm run build
2wrangler pages deploy ./dist --project-name=my-web-app

首次运行时，如果项目尚不存在，则会创建它。在 CI 中，请将交互式的 wrangler login 替换为通过环境变量提供的、作用域受限的 API 令牌，这样就不需要浏览器步骤：

1# .github/workflows/deploy.yml (excerpt)
2- name: Deploy to Cloudflare Pages
3  run: npx wrangler pages deploy ./dist --project-name=my-web-app
4  env:
5    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
6    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

直接上传会跳过 Cloudflare 自己的构建步骤，从而规避构建环境问题，并让你完全掌控工具链。

常见陷阱与故障排除

少数几个问题占据了大多数首次部署失败的原因：

  • 刷新 SPA 路由时出现 404 错误。 诸如 /dashboard 之类的客户端路由会返回 “Nothing is here yet”，因为磁盘上不存在匹配的文件。解决方法是在 _redirects 中使用 /* /index.html 200 回退规则，并确认该文件落在构建输出中，而不是你的源文件夹中。
  • _redirects 或 _headers 似乎被忽略。 这些文件必须位于已发布的输出目录中，而不仅仅是仓库中。对于 Vite、Astro 或 SvelteKit，请将它们放在 public/（或 static/）文件夹中，以便构建时将其原样复制过去。
  • 本地构建成功但在 Cloudflare 上失败。 这几乎总是 Node 版本不匹配或缺少构建时变量所致。请固定 Node 版本并重新声明构建所读取的任何变量——它们与运行时绑定是分开的。
  • “Too many files”或部署过大。 单次部署上限为 20,000 个文件，每个文件限制为 25 MiB。大型媒体应放在 R2 或图片服务中，而不是静态包内。
  • 发布后资源陈旧。 诸如 app.4f2c.js 之类的带哈希文件可以被激进地缓存，但 index.html 不应如此。请让 HTML 保持较短的缓存，并让带指纹的资源保持不可变，如前所示。

测试与生产注意事项

Cloudflare 会为每个非生产分支和拉取请求构建一个预览部署，每个都有自己的 URL（例如 abc123.my-web-app.pages.dev）。由于预览运行在与你线上站点相同的边缘网络上，它们是在合并前审查更改的可靠场所。

对于真正的发布，几项控制机制决定了它究竟是一个托管服务还是一套可靠的工作流：

  • 回滚。 每次部署都会被保留，因此有问题的发布可以通过在 dashboard 中将之前的构建重新提升到生产环境来回退，几秒钟即可完成，无需重新构建。
  • 环境隔离。 为生产环境和预览环境设置不同的变量，以便预览构建指向暂存 API 而不是线上数据。
  • 分析与 Core Web Vitals。 启用 Cloudflare Web Analytics——注重隐私且无 cookie——以在不加载第三方脚本的情况下跟踪真实用户的 LCP、CLS 和流量。
  • 预览的访问控制。 预览 URL 默认是公开的。如果某个分支暴露了未发布的工作，请将其置于 Cloudflare Access 之后，以便只有你的团队才能打开它。

尽早落实这些措施，可以在项目不断壮大、越来越多人向其推送代码时，让你的部署保持可预测。

关键要点

  • Cloudflare Pages 将静态 Web 应用托管在 Cloudflare 的全球边缘网络上，优化加载速度。
  • 通过关联 GitHub 或 GitLab 在每次提交时编译代码，从而自动化部署。
  • 定义与你的框架（Astro、Next.js、Hugo、React）相匹配的构建命令和输出目录。
  • 在你的输出目录中使用简单的 _redirects 和 _headers 文本文件配置重定向和安全标头。
  • 使用由 Cloudflare 直接管理的免费、自动续期的 SSL 证书映射自定义域名。

优化你的 Web 基础设施

部署快速、安全的前端需要选择正确的托管架构和缓存规则。Mecanik 专注于网站开发服务 ，并提供专业的技术 SEO 审计服务 。我们构建针对 Core Web Vitals 优化并部署在 Cloudflare 上的定制 React、Next.js 和 Astro 平台。立即联系我们，商讨你的下一个构建项目。

常见问题（FAQ）

什么是 Cloudflare Pages 托管？ 它是一个无服务器前端托管平台，在 Cloudflare 的 CDN 上于全球范围内构建并提供静态 Web 应用、React SPA 以及静态站点生成器的输出（如 Astro 或 Hugo）。

Cloudflare Pages 是否支持服务端渲染（SSR）？ 是的。Pages 通过在构建过程中自动将服务器逻辑转换为无服务器的 Cloudflare Workers，来支持 SSR 框架（如 Next.js、Astro、SvelteKit）。

如何在 Cloudflare Pages 上配置重定向？ 你在构建输出目录中创建一个名为 _redirects 的纯文本文件，并编写重定向规则，定义源路径、目标路径和 HTTP 状态码。

Cloudflare Pages 是免费的吗？ 是的。Cloudflare Pages 提供了慷慨的免费套餐，包含无限次部署、无限带宽和自定义域名，使其在静态托管方面极具成本效益。

如何在 Pages 上设置自定义域名？ 导航到你的 Pages 项目 dashboard 中的 Custom Domains 选项卡，输入你的域名，Cloudflare 便会配置 DNS 记录并签发一个免费的 SSL 证书。