如何使用 Cloudflare 免费版部署 SPA：完整指南

目录

• 战略概览
• 1. 何时使用 Pages 与 Workers
• 2. 免费版的重要限制

  • 不常见的提示
• 3. SPA 的经典问题：深层路由

  • 不常见的提示
• 4. 环境变量：公开不等于机密

  • 不常见的提示
• 5. 不要将整个 API 放在 SPA 中

  • 不常见的提示：不要为所有内容调用 Functions
• 6. 在部署末尾使用自定义域名
• 7. 保护源和 API
• 8. 利用 Preview Deployments

  • 不常见的提示
• 9. 使用 R2 存储大文件
• 10. 在开发期间避免激进的缓存
• 11. 你应该监控的指标
• 推荐的起始架构
• 结论

Cloudflare 不仅可以加速现有网站，它还可以成为你部署前端、连接 API、管理域名、保护表单和实验无服务器函数的平台。

典型的架构如下：

用户
   ↓
Cloudflare DNS + SSL + CDN
   ↓
Cloudflare Pages
   ↓
静态 SPA：React、Vue、Angular、Svelte 或 Vite
   ↓
外部 API、Pages Functions 或 Workers
   ↓
数据库 / 存储

战略概览

需求	工具	建议
部署前端	Cloudflare Pages	连接 Git 仓库并自动部署
提供静态文件	Pages CDN	利用资产请求的免费和无限制特性
管理域名	Cloudflare DNS	使用自定义域名和代理记录
保护应用程序	WAF Custom Rules	保护登录、注册和敏感端点
创建小型 API	Pages Functions 或 Workers	用于轻量级逻辑和简单端点
存储文件	R2	将图像、PDF 和大文件与前端分离
存储简单数据	KV 或 D1	用于配置、会话或原型
保护表单	Turnstile	仅在存在滥用的地方添加
处理 SPA 路由	_redirects 或 _routes.json	将未知路由发送到 index.html
管理机密	Variables and Secrets	永远不要在前端包中包含私钥
验证更改	Preview Deployments	在生产环境之前审查每个拉取请求
控制成本	限制和分析	分别测量 Pages Functions 和 Workers

1. 何时使用 Pages 与 Workers

对于传统 SPA，最简单的起点是 Cloudflare Pages。

Pages 适用于你的应用程序编译为静态文件时：

npm run build

并生成如下文件夹：

dist/

工作流程如下：

1. 连接 Git 仓库。
2. 选择框架。
3. 定义构建命令。
4. 指定输出文件夹。
5. 每次更改自动部署。

Cloudflare Pages 允许你为不同框架配置命令、输出文件夹、环境变量和预设。(Build configuration)

当你需要以下功能时，使用 Workers：

• 自定义 API。
• 高级中间件。
• 身份验证。
• 请求转换。
• 在边缘执行的逻辑。
• 将前端和后端结合在单个部署中的项目。

实用建议：

首先使用 Pages 部署前端，只有在有具体的后端需求时才添加 Workers 或 Pages Functions。

2. 免费版的重要限制

免费 Pages 计划允许每月最多 500 次构建、一次同时构建、每个站点 20,000 个文件、每个文件最大 25 MiB。它还允许无限制的预览部署。(Pages Limits)

这对于许多个人应用程序、MVP 和小型项目来说已经足够。

但是，不建议直接上传到 Pages：

• 大型视频。
• 安装程序。
• 备份。
• 重型多媒体文件。
• 大型图像集合。

对于这些内容，最好使用 R2 或专用存储，并让 Pages 专门用于应用程序。

不常见的提示

计算你的构建生成的文件数：

Get-ChildItem -Recurse dist | Measure-Object

应用程序在兆字节方面可能看起来很小，但由于源映射、翻译、字体或重复资产，可能会超过文件限制。

3. SPA 的经典问题：深层路由

SPA 在从 / 导航时可能完美运行，但如果用户直接输入：

/dashboard
/settings/profile
/projects/123

可能会显示 404 错误。

发生这种情况是因为服务器查找名为 dashboard 或 settings/profile 的物理文件，尽管这些路由应该由前端路由器解释。

解决方案是将未知路由重定向到 index.html。

在许多 Pages 项目中，你可以在公共文件夹中创建 _redirects 文件：

/* /index.html 200

代码 200 表示浏览器应该接收 index.html 的内容，而不会将路由转换为可见的重定向。

不常见的提示

不要对静态文件或 API 无差别地应用此回退。配置不当的设置可能会将真正的错误，如：

/api/users
/assets/logo.svg
/favicon.ico

转换为 index.html 的 HTML 响应。

始终测试：

• 主路由。
• 内部路由。
• 不存在的路由。
• 浏览器刷新。
• 直接共享的链接。
• 从移动设备访问。

4. 环境变量：公开不等于机密

SPA 在浏览器中运行。因此，构建期间包含的任何变量最终都可能对用户可见。

公开以下内容是有效的：

VITE_API_URL
NEXT_PUBLIC_API_URL
PUBLIC_SUPABASE_URL

但你永远不应该公开：

DATABASE_PASSWORD
STRIPE_SECRET_KEY
JWT_PRIVATE_KEY
CLOUDFLARE_API_TOKEN

公共变量可用于配置前端。机密应保留在 Pages Functions、Workers 或你的后端中。

Cloudflare 允许从项目面板为生产和预览配置不同的变量。(Pages Bindings)

不常见的提示

创建两个独立的环境：

Preview → 测试 API
Production → 真实 API

这样，你可以审查拉取请求，而测试前端不会修改真实数据。

此外，通过 .nvmrc、.node-version 或 NODE_VERSION 显式设置 Node.js 版本。这可以防止构建环境的更改意外破坏部署。(Pages Build Image)

5. 不要将整个 API 放在 SPA 中

SPA 不应直接与需要私钥的服务通信。

不安全的架构：

SPA → 使用私钥的外部服务

推荐的架构：

SPA → Worker 或 Pages Function → 外部服务

Worker 可以：

• 验证接收的数据。
• 检查身份验证。
• 应用速率限制。
• 隐藏凭据。
• 规范化响应。
• 记录错误。

Pages Functions 作为 Workers 运行，其请求计入 Workers 配额。在免费计划中，组合配额为每天 100,000 次请求。(Pages Functions Pricing)

不常见的提示：不要为所有内容调用 Functions

如果你在 Pages 项目中添加 Function 而不配置路由，你可能会为只应提供静态文件的请求执行动态逻辑。

配置路由，使 Function 仅响应：

/api/*

并将资产保留为静态内容。Cloudflare 允许定义包含和排除路由来控制哪些请求调用 Functions。(Pages Functions Routing)

6. 在部署末尾使用自定义域名

首先在以下位置测试应用程序：

my-app.pages.dev

然后连接：

app.example.com

这样可以轻松分离：

app.example.com       → 生产
staging.example.com   → 测试
api.example.com       → API
assets.example.com    → 大文件

为 HTTP 和 HTTPS 流量启用 Cloudflare 代理，但将不兼容 Web 代理的服务（如某些邮件记录）保留为 DNS-only。

7. 保护源和 API

如果前端在 Pages 上但 API 位于另一台服务器上，也要保护该源。

建议措施：

• 不必要地不暴露后端 IP。
• 在 API 上应用身份验证，而不仅仅是在前端。
• 验证 CORS。
• 限制对 /api/login、/api/register 和 /api/reset-password 的请求。
• 在被攻击的表单上使用 Turnstile。
• 在阻止用户之前应用 Managed Challenge。

Cloudflare 的自定义规则允许执行阻止或质询请求等操作。在免费计划中，有数量和功能限制，因此建议为关键路由保留它们。(Custom Rules)

8. 利用 Preview Deployments

对小团队最有用的功能之一是每个拉取请求都有一个预览 URL。

推荐的工作流程：

拉取请求
   ↓
预览部署
   ↓
视觉和功能测试
   ↓
合并到生产

这对于 SPA 特别重要，因为它允许检测：

• 返回 404 的路由。
• 缺失的环境变量。
• CORS 错误。
• 移动设备上的损坏更改。
• 缓存问题。
• 身份验证失败。

不常见的提示

在你的应用程序中包含一个指示环境的小视觉标签：

Preview · commit a81f2c

这样，在审查期间没有人会混淆测试 URL 和生产 URL。

9. 使用 R2 存储大文件

SPA 包应该只包含运行应用程序所需的内容。

保留在 Pages 之外：

• 用户上传的图像。
• 视频。
• PDF。
• 项目文件。
• 备份。
• 生成的导出。

R2 专为对象存储设计，可与 Workers 或你自己的 API 一起使用。在 Cloudflare 的当前产品中，免费计划包括 R2 的存储和操作配额。(Cloudflare Plans)

简单的架构如下：

SPA → Worker → R2

Worker 生成受控的 URL，并防止存储桶成为完全开放的访问点。

10. 在开发期间避免激进的缓存

Cloudflare 可以长时间缓存前端文件。这在生产环境中是积极的，但在开发时可能会令人沮丧。

为了避免问题：

• 为 CSS 和 JavaScript 使用带版本号的名称。
• 不要缓存私有响应。
• 清除特定 URL 而不是清除所有内容。
• 在快速更改期间使用开发模式。
• 检查 CF-Cache-Status。
• 记住浏览器缓存可能在 Cloudflare 清除后仍然存在。

免费计划允许缓存规则、缓存清除和缓存分析，尽管限制比高级计划低。(Cache Features by Plan)

11. 你应该监控的指标

对于 SPA，仅测量访问量是不够的。

观察：

• 主 JavaScript 加载时间。
• 缓存响应的百分比。
• 内部路由的 404 错误。
• API 的 4xx 和 5xx 错误。
• Function 请求。
• Workers 的每日使用量。
• 每个请求的 CPU 时间。
• 身份验证错误率。
• 包大小。
• 表单放弃率。

免费 Workers 计划有每天 100,000 次请求和每个请求 10 毫秒 CPU 的限制。小函数可能工作良好，但处理图像、验证复杂用户或执行繁重计算的函数可能会超过该限制。(Workers Limits)

推荐的起始架构

Cloudflare DNS
      ↓
Cloudflare Pages
      ↓
静态 SPA
      ↓
Pages Functions / Workers
      ↓
外部数据库或 D1
      ↓
文件用 R2

对于 MVP，你可以从以下开始：

• 用于前端的 Pages。
• 用于 API 的 Worker 或 Pages Function。
• 用于数据库的 Supabase、Neon 或 D1。
• 用于文件的 R2。
• 用于敏感表单的 Turnstile。
• 用于审查更改的 Preview Deployments。

结论

Cloudflare 的免费层级对于部署 SPA 特别有趣，因为它结合了静态托管、CDN、HTTPS、自定义域名、预览和无服务器函数。

最高效的策略是：

1. 首先在 Pages 上部署前端。
2. 正确解决 SPA 路由。
3. 将公共变量与机密分离。
4. 仅对动态逻辑使用 Functions 或 Workers。
5. 将大文件存储在 R2 中。
6. 保护登录、注册和 API。
7. 测量消耗、错误和性能。
8. 仅在存在实际限制时扩展。

Cloudflare 不会自动取代整个后端，但它确实允许使用模块化架构构建功能性、安全且相当经济的 Web 应用程序。