5650 字
28 分钟
Cloudflare Pages 部署静态网站

上一篇我们用 Workers 在边缘跑起了代码,但回头想想:绝大多数个人网站根本不需要”跑代码”——博客、文档站、作品集、落地页,本质上都是一堆生成好的 HTML、CSS、JavaScript 和图片文件。给这种站点专门开一台服务器,等于为了放几本书租了一间仓库:要打理系统、要续证书、要防入侵,还要为带宽和电费买单。

Cloudflare Pages 就是为这类站点准备的托管服务:你把代码推到 Git 仓库,它自动拉取、构建、把产物分发到 Cloudflare 的全球边缘网络,访客从离自己最近的节点拿文件。没有服务器要维护,没有证书要续期,HTTPS 自动配好。这一篇我们把 Pages 的两条部署路线——连接 Git 自动部署和手动上传——完整走一遍,再讲清构建设置、自定义域名、预览部署、回滚这些日常真正会用到的东西,最后和”自己拿服务器托管静态站”做一次老实的取舍对比。

主线先说清楚:先分清 Pages 和 Workers 各管什么,再走路线 A(连接 Git),逐项拆解构建设置,然后走路线 B(手动部署),接着绑自定义域名、用好预览部署与回滚,顺手认识 _redirects、_headers、_routes.json 三个进阶文件,文末是排障小节。

先分清:Pages 和 Workers 各管什么#

上一篇的 Workers 是”在边缘运行你的 JavaScript 代码”,适合需要逻辑判断的场景:改写请求、做接口、鉴权、A/B 分流。Pages 则是”在边缘托管你的静态文件”,适合内容在构建期就已经定型的站点。两者不是二选一的对手,而是分工不同的两件工具:

维度Cloudflare PagesCloudflare Workers
本质静态文件托管 + 全球分发边缘函数运行时
产物HTML / CSS / JS / 图片等文件一段处理请求的函数代码
适合博客、文档、官网、作品集、单页应用接口代理、鉴权、改写、动态逻辑
部署方式推 Git 自动构建,或直接上传产物Wrangler 发布脚本
要不要写服务端代码不需要需要
收费模式静态请求免费额度慷慨,细则以控制台为准按请求与 CPU 时间计,细则以控制台为准

还有一个组合用法先点一句:Pages 项目里可以放一个 functions 目录,里面的文件会被当作 Pages Functions 运行——它底层就是 Workers。也就是说,纯静态站用 Pages,哪天某个路径需要一点动态逻辑(比如表单提交、简单接口),不用搬家,在 Pages 里加 Functions 就行。本篇以纯静态部署为主,Functions 只在后面的 _routes.json 部分露个脸。

判断标准只有一条:内容在构建时能不能定死。能定死,归 Pages;必须按请求现算,归 Workers。

路线 A:连接 Git 仓库自动部署#

这是 Pages 的主线用法,也是推荐给长期维护站点的路线:本地写完,git push,剩下的事全自动。整个过程分四步。

第一步:授权并选择仓库#

进入 Cloudflare 控制台,左侧进入 Workers 和 Pages,点 创建,选择 Pages,再选 连接到 Git。第一次使用会跳转到 GitHub(或 GitLab)做 OAuth 授权,这里有个容易忽略的细节:授权时可以选择只授权某几个仓库,不必把全部仓库都交出去。按最小授权原则,只勾选要部署的那个仓库就够了。

授权完成后回到控制台,在仓库列表里选中目标仓库,点 开始设置。

第二步:配置构建设置#

接下来是最关键的一屏:项目名称、生产分支、框架预设、构建命令、构建输出目录。

  • 项目名称:会成为默认访问地址的一部分,比如填 my-blog,默认域名就是 my-blog.pages.dev,创建后不可改名,起名字时想清楚。
  • 生产分支:一般是 main 或 master。推到这个分支的提交触发生产部署,其他分支触发预览部署(后面专门讲)。
  • 框架预设:下拉里选你用的框架,Cloudflare 会自动填好构建命令和输出目录。选对了,后面两项基本不用动。

三个最典型的框架,预设填法对照如下:

框架构建命令构建输出目录
Astronpm run builddist
Hugohugopublic
纯静态(无构建)留空/(直接填仓库根目录,或填存放 HTML 的目录名)

纯静态站点没有构建步骤,构建命令留空即可,输出目录填文件所在的目录;如果 HTML 就在仓库根目录,填 / 或者直接留默认。

第三步:保存并部署#

点 保存并部署,控制台会跳进构建日志页面,实时滚动输出:克隆仓库、安装依赖、执行构建命令、上传产物。第一次构建通常一两分钟。成功后页面顶部会给出形如 https://my-blog.pages.dev 的地址,点开就能看到你的站点——这一刻它已经在全球边缘节点上对外服务了。

第四步:验证自动部署#

在本地随便改一个字,提交并推送到生产分支:

Terminal window
git add .
git commit -m "test auto deploy"
git push origin main

回到控制台的部署列表,应该能看到一条新的构建正在排队或运行。从此你的发布流程就只剩 git push 一个动作,构建失败时控制台会把日志停在出错的那一步,排障部分会讲怎么读。

WARNING

Git 授权是长期有效的凭证,仓库里如果混进了密钥、令牌这类敏感文件,推送前务必先清理并写进 .gitignore。把带密钥的仓库连上任何自动部署平台,等于把密钥又复制了一份到第三方。

构建设置逐项拆解#

第一次配置时匆匆带过的几个字段,日后出问题基本都出在它们身上,逐个讲清。

构建命令#

构建命令是在 Cloudflare 的构建环境里执行的 shell 命令,工作目录默认是仓库根目录。多数框架就是包管理器的一条脚本命令:

Terminal window
npm run build # Node 系框架最常见
pnpm run build # 用 pnpm 的项目
hugo --minify # Hugo 也可以追加参数

命令执行失败(退出码非 0),整个部署就失败,不会拿旧产物顶替——这点是好事,不会出现”以为更新了其实没更新”的静默事故。

构建输出目录#

构建产物所在的目录,相对于仓库根目录写。比如 Astro 产物在 dist,就填 dist;Hugo 在 public,填 public。这是所有设置里最容易填错、也是 404 故障的头号来源,排障部分会再强调。注意不要写成绝对路径,也不要多带一层:产物里直接就是 index.html 的那一层目录,才是输出目录。

根目录(高级设置)#

如果你的站点代码不在仓库根目录,而是放在子目录里(比如一个仓库放多个项目,博客在 blog/ 下面),展开 高级设置,把根目录填成 blog。构建命令和输出目录都会以这个根目录为基准计算。单项目仓库保持默认空着即可。

环境变量#

构建期需要注入的变量在这里配置,最常见的用途是指定运行时版本。Cloudflare 构建环境的 Node.js 默认版本未必和你本地一致,版本对不上时构建报错信息往往很隐晦。稳妥做法是显式声明:

变量名示例值作用
NODE_VERSION20指定 Node.js 大版本
HUGO_VERSION0.128.0指定 Hugo 版本(需要扩展版时另有变量)
PYTHON_VERSION3.11指定 Python 版本

也可以在仓库根目录放一个 .nvmrc 文件写上版本号,效果相同且能跟着代码一起版本管理,团队协作时更推荐这种方式。

另一个关键点:生产环境和预览环境的环境变量是分开配置的。控制台里切换到”预览”页签单独设置。比如预览环境想连测试接口、加统计排除标记,就只写在预览那一份里,别让预览构建污染生产配置。反过来,生产专用的变量也不要顺手勾选”同时用于预览”,先想一想再勾。

路线 B:手动部署#

不是所有场景都适合连 Git:手里只有一个构建好的成品文件夹、临时要发个演示页、或者代码不方便进 GitHub。这时走手动路线。

方式一:控制台拖拽上传#

在创建 Pages 项目时选择 上传资产,把构建产物文件夹(或打包好的 ZIP)直接拖进浏览器,命名项目,部署完成。整个过程不到一分钟,适合一次性页面和临时演示。

注意上传的是构建产物,不是源代码:Astro 项目要先在本地 npm run build,把生成的 dist 文件夹拖上去;纯静态站点则直接拖放着 HTML 的文件夹。

方式二:Wrangler 命令行#

Wrangler 是 Cloudflare 的官方命令行工具,装好之后一条命令就能部署,适合写进脚本或本地工作流:

Terminal window
# 全局安装 Wrangler
npm install -g wrangler
# 登录 Cloudflare 账号(会打开浏览器授权)
wrangler login
# 部署指定目录为 Pages 项目
wrangler pages deploy dist --project-name my-blog

几个参数说明:dist 是要部署的产物目录,换成你自己的;--project-name 对应控制台里的项目名,项目不存在时 Wrangler 会引导你新建;后续更新同一个项目,再执行同一条命令即可,会生成一条新的部署记录,同样支持回滚。

两种手动方式的取舍很简单:偶尔点一次,用拖拽;要反复发、或者想把部署写进自己的发布脚本,用 Wrangler。

WARNING

手动部署没有”推代码即上线”的自动链路,最大的风险是改完代码忘了重新构建、把旧产物又传了一遍,页面看起来”更新了”其实没变。长期维护的站点,还是回到路线 A 让流程自动跑。

自定义域名#

*.pages.dev 地址能用,但正经站点都要绑自己的域名。Pages 的自定义域名在项目里 设置 → 自定义域 中添加,分两种情况。

绑定子域名#

比如把 blog.example.com 绑到 Pages 项目,前提是这个域名已经托管在 Cloudflare(DNS 在 Cloudflare 这边)。满足前提时,添加域名后 Cloudflare 会自动在 DNS 里生成一条指向该 Pages 项目的 CNAME 记录,你什么都不用手动配,等状态变为”有效”即可,HTTPS 证书也是自动签发、自动续期。

如果域名不在 Cloudflare 托管,就需要去外部 DNS 服务商那里手动添加 CNAME 记录指向 项目名.pages.dev,再回来等验证。能托管过来的域名,建议先转托管,省掉后续所有手动对接的麻烦(接入方法见本系列前面的域名接入篇)。

绑定根域(apex 域名)#

把 example.com 本身(不带任何前缀)绑到 Pages,有个协议层面的前提:DNS 规范里根域不能直接写 CNAME 记录。Cloudflare 的处理方式是它自家的 CNAME 展平(CNAME Flattening)技术——你在控制台照常添加根域,它在解析层把这条记录动态展平成 A 记录对外应答。所以根域绑定只在域名托管于 Cloudflare 时才顺畅,这也是把 DNS 托管过来的又一个实际理由。

实务上更常见的搭配是:根域和 www 子域名都绑上,选一个作主域名,另一个用重定向跳过去(重定向的写法在下面 _redirects 一节),避免两个地址各发一份内容。

证书方面不用操心:自定义域名生效后边缘证书自动覆盖这个域名。但要注意刚添加时状态会经历”正在验证 → 签发证书 → 有效”的过程,几分钟内访问可能报证书错误,等状态变绿再对外宣布地址。

预览部署:每个分支一个网址#

这是 Pages 用过就回不去的功能。连接 Git 的项目里,推到非生产分支的每一次提交、每一个 Pull Request,都会生成一个独立的预览地址,形如:

https://分支名.项目名.pages.dev
https://一串哈希.项目名.pages.dev

预览部署和生产环境完全隔离:产物独立、地址独立,还能套用预览环境专属的环境变量。它的正确用法是一条纪律:新文章、新改版先推到分支上,打开预览地址在手机和电脑上都验一遍,确认没问题再合并到生产分支上线。出了问题也只烂在预览里,线上访客毫不知情。

反过来也要克制:预览地址默认是公开可访问的(知道地址就能打开),不要把未发布的敏感内容、内部页面长期挂在预览部署上等人猜地址。团队项目可以在控制台开启访问控制限制预览的可见范围,个人项目则养成习惯:验完就删分支,预览随分支删除而失效。免费版能保留的部署数量、预览的保留时长等细节以控制台为准。

版本与回滚#

Pages 的每一次部署(无论来自 Git 推送还是手动上传)都会在项目的 部署 列表里留一条记录:时间、分支、提交信息、构建状态,一目了然。生产环境当前正在服务的,是列表中标记为生产的那一条。

如果刚上线的一版出了问题——文章排版崩了、构建产物缺文件——不需要手忙脚乱改代码重发。在部署列表里找到上一个正常的版本,点右侧菜单选择 回滚到此部署,确认后生产流量立即切回那一版产物,秒级生效。回滚切的是已经构建好的产物,不重新构建,所以快。

两个注意点:第一,回滚只是把线上指回旧产物,代码仓库里的错误提交还在,事后必须把代码修好再正常发布,否则下一次推送又会把坏版本带上线;第二,预览部署之间互不影响,回滚操作只针对生产环境当前生效的那条。

回滚是止血,不是修 bug:先回滚恢复线上,再回头慢慢查代码。

三个进阶文件#

把下面三个纯文本文件放在构建输出目录的根部(用框架的项目通常是放在静态资源目录里,让它们被复制进产物),Pages 会在边缘按它们的规则处理请求。不用写代码,就能补上静态托管最常缺的三块能力。

_redirects:跳转规则#

每行一条规则,源路径在前、目标在后、状态码可选:

/old-post /new-post 301
/blog/* /posts/:splat 301
/www / 302

第一列是匹配路径,* 是通配符,命中的部分用 :splat 引用;状态码不写默认 302,永久迁移记得写 301。域名层面的跳转(比如 www 跳根域)也可以在这里按路径层面近似处理,或者去 Cloudflare 的重定向规则里做,本系列的规则改写篇讲过那套体系,按需选一处配置即可,不要两边重复配同一件事。

_headers:自定义响应头#

给指定路径统一附加响应头,常用于安全头和缓存策略:

/*
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
/assets/*
Cache-Control: public, max-age=31536000, immutable

第一段给全站加基础安全头;第二段给带指纹的静态资源设置一年长缓存。缩进和冒号格式要严格照抄,写错一行那一组就不生效且不报错,改完务必用浏览器开发者工具或 curl -I 验一下响应头真的出现了。

_routes.json:控制 Functions 的范围#

只有当项目里用了 Pages Functions 时才需要它。它决定哪些路径的请求要经过 Functions 处理、哪些直接发静态文件:

{
"version": 1,
"include": ["/api/*"],
"exclude": []
}

上面这份配置的意思是:只有 /api/* 走函数,其余路径全部按静态文件直出。这样既省函数调用次数,也避免函数逻辑意外拦截静态资源。纯静态项目没有 functions 目录,这个文件写不写都无效果,可以跳过。

和自建服务器托管静态站的取舍#

最后一张对比表,把 Pages 和”自己拿一台 VPS 用 Nginx 托管静态站”摆在一起。没有谁全面胜出,只有哪种更贴合你当前的阶段:

维度Cloudflare Pages自建服务器 + Nginx
直接成本免费额度内零成本,细则以控制台为准服务器月租 + 域名,持续支出
日常运维无服务器、无补丁、无证书续期系统更新、证书、日志、备份全要自己管
访问速度全球边缘节点就近分发取决于机房位置,远距离访客慢
发布流程git push 自动构建部署自己写脚本或手动传文件
控制力平台规则内使用,进阶靠三个配置文件完全自主,任何 Nginx 玩法都可以
风险面平台政策与额度调整不受你控制机器故障、被攻击、欠费停机都是你的事
适合博客、文档、官网等纯静态内容需要特殊服务端逻辑、或就是想练手折腾

结论很实际:纯静态内容放在 Pages,是在用平台的规模换自己的时间;除非你有明确的特殊需求,或者享受折腾服务器本身,否则没必要为几页静态文件养一台机器。真有动态需求,先想 Pages Functions 和 Workers 补不补得上,再考虑回自建。

排障#

构建失败:先学会看日志的哪一行#

构建失败时控制台会把完整日志摆出来,不要从头读到尾,直接拉到日志末尾往上找第一处报错。失败九成集中在三类:

  1. 依赖安装失败:日志停在 npm install 一带,多半是依赖版本与 Node 版本不兼容,或锁文件(package-lock.json 等)没提交进仓库。先在高级设置里用 NODE_VERSION 对齐本地版本,再确认锁文件在仓库里。
  2. 构建命令失败:日志里能看到你配的命令本身报错,比如脚本名写错、框架在构建机上缺环境变量。把报错命令复制到本地终端跑一遍,本地能复现就先在本地修好。
  3. 命令成功但产物不对:日志显示构建成功,部署却 404——这不是构建失败,是下一条的问题。

部署成功但页面 404:先查输出目录#

部署状态绿了、地址能打开却只有 404,第一嫌疑永远是构建输出目录配错:Astro 的产物在 dist,你填了 public;或者站点在子目录,根目录没配。判断方法很简单:看构建日志最后阶段上传的文件列表里有没有 index.html,没有就是目录指错了层。改对输出目录后重新部署(推一个空提交或在控制台点重试部署)即可。

还有一种情况是单页应用(SPA):前端路由的路径在服务器上并不存在对应文件,直接访问子路径会 404。这需要在框架侧开启 SPA 模式支持,或用 _redirects 把未命中路径兜底到 index.html(状态码用 200 的重写写法),按框架文档确认后再配。

自定义域名一直”待验证”#

按顺序排查三件事:

  1. DNS 记录冲突:同名记录已经存在一条 A 记录或指向别处的 CNAME,新记录加不进去。去 DNS 管理里把冲突的旧记录删掉,再回 Pages 里重新添加域名。
  2. 记录指错目标:域名不在 Cloudflare 托管、手动配 CNAME 的,检查目标是不是写成了带 https:// 的完整网址——CNAME 的值只能是主机名 项目名.pages.dev,不带协议、不带路径。
  3. 只是还没生效:DNS 修改和证书签发都需要几分钟,状态没变绿之前先耐心等,不要反复删除重加——每重加一次,验证流程就从头再来一遍。

如果等待时间明显超出正常范围,再去看域名的 DNSSEC 状态:从别处新迁入的域名若残留旧的 DS 记录,会导致解析验证失败,需要在注册商处删除旧 DS 记录或按 Cloudflare 给的值更新,这一步对新手最隐蔽,卡住超过半小时优先查它。

小结#

  • Pages 管静态、Workers 管逻辑,内容构建期能定死就用 Pages,需要动态再加 Functions 或 Workers。
  • 路线 A 连接 Git 是长期站点的正道:授权时最小化仓库范围,框架预设选对,构建命令与输出目录照框架的规矩填。
  • 构建设置里最容易翻车的是输出目录,其次是 Node 版本;环境变量分生产与预览两套,别混用。
  • 路线 B 手动部署分拖拽和 Wrangler 两种,适合临时页面与脚本化发布,长期维护别靠它。
  • 自定义域名在 Cloudflare 托管下子域名自动配记录,根域靠 CNAME 展平实现,证书全自动。
  • 预览部署是上线前的验收场,先验后合并;回滚是秒级止血手段,但代码里的错误仍要修掉。
  • _redirects、_headers、_routes.json 三个文件,分别补上跳转、响应头和函数范围三块能力。

下一篇我们讲 Cloudflare Access:给那些必须放在公网、又不想裸奔的自建服务后台,套一层正经的登录门禁。

Cloudflare Pages 部署静态网站
https://www.anexns.cloudns.org/posts/cloudflare-pages-deploy/
作者
Anexns
发布于
2026-11-15
许可协议
CC BY-NC-SA 4.0