Cloudflare Pages 部署与排错指南

更新于 2026-11-02 · hgfastapp.lol

简答：Cloudflare Pages 是面向静态资源和部分动态功能的网站部署平台。新项目先判断是否需要 Workers；纯静态站可用 Git 集成、Direct Upload 或命令行部署。部署前最容易出错的是构建命令、输出目录、Root directory 和 SPA 路由，先核对这四项，再绑定域名。

定义：Cloudflare Pages 是把静态网站及 Pages Functions 部署到 Cloudflare 全球网络的托管平台，支持 Git 集成、Direct Upload 和命令行部署。

先看速查：Cloudflare Pages 该怎么选

如果你现在只是想把 HTML、React、Vue、Hugo 或其他静态构建产物上线，先按下表选择部署方式。Cloudflare 官方文档同时提示，Workers 支持大多数 Pages 使用场景，并且是构建应用的主要平台；因此新项目不要只看“能不能部署”，还要看后续是否需要更复杂的服务端能力。可先阅读 Cloudflare Pages 官方概览。

你的项目情况	优先方式	理由与注意点
代码放在 GitHub 或 GitLab，希望推送后自动发布	Git integration	支持自动构建、预览部署和生产分支；选择后不能直接切换为 Direct Upload。
已有构建产物，想从本地电脑或自有流水线上传	Direct Upload	适合上传预构建文件；选择后不能直接切换为 Git integration。
想在终端执行部署、管理项目或接入自动化流程	Wrangler 或 C3	适合命令行和持续集成，具体参数以当前官方 CLI 文档为准。
需要服务端逻辑、数据绑定或更完整的应用能力	评估 Workers	Pages Functions 可提供动态功能，但其请求计入 Workers 相关用量。

关键选择：Git integration 与 Direct Upload 不是随时互换的开关。选错时，稳妥回退通常是新建项目并重新选择部署方式，而不是反复修改原项目。

从本地网站到上线：最短部署闭环

准备项目目录。纯静态 HTML 至少确认入口文件位于最终发布目录中，通常是 index.html。官方静态 HTML 指南说明，不使用框架或静态站点生成器的网站也可以部署到 Pages：Static HTML 部署说明。
先在本地完成构建。React（Vite）常见构建命令是 npm run build，输出目录通常为 dist；Vue、Astro 等项目也有各自的默认目录。不要凭经验填写，先以项目实际生成的目录为准。
选择部署入口。使用 Git integration 时，连接 GitHub 或 GitLab，选择生产分支并填写构建命令和输出目录；使用 Direct Upload 时，先完成本地构建，再上传预构建资产。两种流程分别见 Git integration 和 Direct Upload。
核对四个配置。构建命令、Build directory、Root directory、环境变量必须互相匹配。没有框架构建命令的项目可按官方说明使用 exit 0；非零退出码会被判定为构建失败，Root directory 则用于 monorepo 等子目录项目。具体规则见 Build configuration。
先访问 pages.dev 地址。不要一开始就把问题复杂化到 DNS。先确认默认地址能打开、首页资源正常、刷新子路径不会出现错误，再进入自定义域名配置。
最后绑定自定义域名。在 Cloudflare 控制台进入 Workers & Pages，选择项目的 Custom domains，再选择 Set up a domain。官方步骤见 Custom domains。域名解析未生效时，先检查记录是否指向当前项目，并等待 DNS 变化完成。

成功标准：默认域名能打开首页，浏览器开发者工具没有明显资源 404，项目生产部署状态成功，自定义域名可以通过 HTTPS 访问。任一项不满足时，先回到默认域名和最近一次成功部署，不要同时修改构建、DNS 和路由。

费用与主要限制：不要只看“静态资源免费”

截至 2026-11-02，官方文档明确说明：静态资源请求在免费和付费计划中均免费且不限量；但 Pages Functions 请求按 Cloudflare Workers 请求计费，且相关 KV 或 Durable Objects 绑定请求也会计入 Workers 计划用量。具体金额和 Workers 套餐应以当前计费页面为准，本文不代填未在本次资料中核实的价格。来源见 Pages Functions pricing。

项目	官方已核实信息	实际影响
静态资源请求	免费且不限量	纯静态博客、文档站和前端展示页通常不因静态请求本身产生 Pages Functions 费用。
Git 构建	Free 计划每月 500 次构建；同时构建数为 1；单次构建 20 分钟后超时	频繁提交、构建时间过长或大型依赖项目需要关注构建额度和超时。
自定义域名	Free 计划每个项目最多 100 个自定义域名	多站点或多租户项目要先确认项目数量和域名规划。
文件数量与大小	Free 计划最多 20,000 个文件；单个资产最大 25 MiB	大文件、图片库或下载资源应考虑拆分到对象存储，而不是全部塞进 Pages。
项目数量	每个账户最多 100 个 Pages 项目	大量站点管理需要评估其他 Cloudflare 产品或账户规划。

以上限制来自 Cloudflare Pages Limits。限制会随计划和官方文档变化，付款或架构定案前应重新核对当前条款。

Pages、Pages Functions 与 Workers 怎么判断

选 Pages：网站主要由预构建 HTML、CSS、JavaScript 和图片组成，希望获得 Git 自动部署、预览环境、回滚和自定义域名。
加 Pages Functions：需要少量服务端路由、表单处理、鉴权或动态响应，但仍希望保留 Pages 的网站部署流程。需要同步关注 Workers 请求用量。
直接评估 Workers：项目从一开始就是应用或 API，服务端逻辑占核心地位，或者预计会大量使用运行时能力、数据绑定和更复杂的路由。官方 Pages 概览已提示，Workers 支持大多数 Pages 使用场景并提供更广泛的功能。

这不是“Pages 一定会被停止”的结论，而是当前官方文档给出的选型信号。最稳妥做法是按项目当前需求选择，并保留迁移路径；不要仅凭社区讨论判断产品状态。

常见错误排查：按现象分流

1. 部署成功但首页 404

先检查输出目录中是否真的存在 index.html，再检查 Build directory 是否填到了构建产物所在位置。静态文件的路径匹配和 HTML 页面处理规则可参考 Serving Pages。如果是单页应用，刷新非首页路径出现 404，还要检查 SPA 回退策略、路由配置或项目框架的静态导出设置。

2. 构建失败或提示目录为空

在本地执行同一条构建命令，确认退出码为 0，并查看实际生成的目录名称。对于 monorepo，Root directory 不能默认指向仓库根目录；环境变量也应在项目设置中分别核对。不要为了“让构建通过”把错误命令改成 exit 0，除非项目确实没有需要执行的构建步骤。

3. 页面能访问但图片、脚本加载失败

打开浏览器开发者工具查看失败资源的实际 URL，检查大小写、相对路径、基础路径和构建后的文件位置。若资源超过单文件限制，不要继续重复上传，应重新评估资源拆分或对象存储方案。

4. 自定义域名没有打开

先用 pages.dev 地址确认项目部署本身正常，再检查自定义域名是否已经添加到正确项目、DNS 记录是否与控制台提示一致，以及是否存在旧记录冲突。DNS 尚未生效时不要频繁改动多条记录；保留当前配置并按解析状态逐项验证。

5. 新版本上线后想恢复旧版本

Pages 支持回滚到之前的生产部署。先记录当前异常现象和部署编号，再使用项目的 Rollbacks 功能恢复已知正常版本，之后单独修复构建或路由问题。相关说明见 Rollbacks。

上线前检查清单

项目类型已确认：纯静态、框架静态导出，还是需要 Functions/Workers。
Git integration 与 Direct Upload 的选择符合长期工作流。
构建命令、输出目录和 Root directory 已在本地或构建日志中验证。
首页文件、资源路径、SPA 刷新路径均已测试。
默认 pages.dev 地址先通过，再绑定自定义域名。
环境变量没有把密钥硬编码进前端静态文件。
已查看当前构建次数、文件数量、单文件大小和 Functions 用量限制。
保留最近一次成功部署，出现问题时优先回滚，不要同时改动所有配置。

如果资料、账户权限、域名归属或当前计费条款无法互相印证，应先停止付款和导入，回到 Cloudflare 控制台与官方文档核验。

常见问题

Cloudflare Pages 免费吗？

静态资源请求在免费和付费计划中均免费且不限量，但构建次数、文件数量、项目数量和 Pages Functions 用量存在限制。Functions 请求按 Workers 相关规则计费，具体套餐金额需要以当前官方计费页面核实。

Cloudflare Pages 和 Direct Upload 可以互相切换吗？

官方文档说明，使用 Git integration 的项目不能直接切换为 Direct Upload；使用 Direct Upload 的项目也不能直接切换为 Git integration。若要更换工作流，通常需要新建项目，或按官方支持的命令行方式调整部署流程。

Cloudflare Pages 部署后为什么是 404？

优先检查输出目录中是否存在 index.html、Build directory 是否填对，以及项目是否属于需要 SPA 回退的单页应用。默认 pages.dev 地址也应先测试，确认是构建问题还是自定义域名、DNS 或路由问题。

Cloudflare Pages 能部署 React 或 Vue 吗？

可以，官方构建配置列出了 React（Vite）和 Vue 等常见项目的构建命令与输出目录。实际填写前仍应以项目生成结果和当前框架配置为准，不能只照抄其他项目的目录。

什么时候不建议只用 Cloudflare Pages？

如果项目核心是 API、复杂服务端逻辑、持续运行任务或大量运行时数据操作，应把 Workers 或其他后端架构纳入评估。Pages 更适合静态资源和以网站交付为主的项目，Pages Functions 适合补充有限动态能力。