2639 字
13 分钟
阅读量加载中
Cloudflare Pages 部署静态博客:Git 自动构建、自定义域名与免费额度边界
2026-11-06
2026-11-06

这篇记录我把一个 Astro 静态博客从 GitHub 接到 Cloudflare Pages 的过程。它和前面两篇的区别很简单:不拖拽上传,也不依赖 Gitee,而是让 Pages 直接监听 GitHub 仓库,每次 git push 自动构建。免费额度、构建环境和控制台文案都可能调整,操作前以 Cloudflare 控制台显示为准。

一、先确认你要解决的是哪一步#

同样是“把静态站发上线”,目前有三条常见路线:

方案适合谁更新方式主要限制
Cloudflare Drop手上只有一组 HTML 文件,没有仓库每次手动上传文件夹不自动同步,改一次传一次
EdgeOne Pages用 Gitee 托管、主要面向国内推送仓库后自动构建免费套餐的节点和配额有限
Cloudflare Pages代码在 GitHub、想要分支预览推送仓库后自动构建国内访问一般不占优势

本文走第三条。它的核心不是“免费托管”,而是把发布流程变成一次普通的代码提交:本地构建通过 → 推到 GitHub → Pages 自动构建 → 生产域名更新。

二、前置条件#

开始之前,确认下面四件事:

  • 一个 GitHub 仓库,代码已经推上去;
  • 一个 Cloudflare 账号,免费计划就够;
  • 本地能跑通构建命令,知道输出目录是哪个;
  • 一个域名(可选;没有也能先用 *.pages.dev 子域名)。

先在本地验证一次,不要跳过:

Terminal window
npm ci
npm run build

构建完成后确认输出目录存在,例如 dist/、out/ 或 public/。如果本地都跑不通,Pages 上大概率也会失败。

三、先把仓库整理成“可被 Linux 构建”的状态#

Cloudflare Pages 的构建机是 Linux,本地是 Windows 时,下面几处最容易出问题:

  1. 提交 lockfile:package-lock.json、pnpm-lock.yaml 或 yarn.lock 要进仓库,构建时用 npm ci 才能复现依赖。
  2. 不要提交 node_modules 和 dist:构建产物交给 Pages 生成,仓库里只保留源码。
  3. 注意文件名大小写:Windows 不区分大小写,Linux 区分。Components/Header.astro 和 components/header.astro 在本地可能都能引用,到构建机就报找不到。
  4. 固定 Node 版本:Pages 默认版本可能和本地不同,建议在仓库根目录加 .nvmrc,或在控制台设置 NODE_VERSION 环境变量。填你本地验证过的版本,例如:
22
  1. 原生依赖要留意:sharp 这类带平台二进制的包,本地 Windows 能装不代表 Linux 构建机也能装。遇到构建报错时,先看日志里是哪个包、哪个平台。

四、在 Cloudflare 创建 Pages 项目#

控制台入口会随改版变化,按下面的路径找:

Workers & Pages
→ Create application
→ Pages
→ Connect to Git

然后:

  1. 授权 Cloudflare 访问 GitHub;
  2. 选择要部署的仓库;
  3. 填写项目名,例如 my-blog;
  4. 选择生产分支,一般是 main;
  5. 填写构建命令和输出目录;
  6. 保存并部署。

第一次部署会完整跑一遍依赖安装和构建。日志里能看到每一步的耗时,失败时也会停在具体命令上。

五、构建配置对照表#

框架预设只是帮你填默认值,提交前仍要自己核对一遍:

项目类型构建命令输出目录备注
Astronpm run builddist静态输出,默认适配
Vitenpm run builddist注意 base 路径
Next.js 静态导出npm run buildout需要 output: 'export',不能用服务端功能
Hugohugopublic确认主题依赖已拉取
纯 HTML留空/仓库根目录就是站点根目录

几个容易踩的坑:

  • Next.js 的 SSR / ISR 不能直接跑在 Pages 的纯静态托管上。要用静态导出,或者改用带服务端的方案。
  • Vite / Astro 的 base:如果站点部署在子路径,构建时的 base 要和实际访问路径一致,否则 CSS、JS 会 404。
  • Monorepo:如果项目在子目录,构建时要把“根目录”指到对应包,否则 Pages 会在仓库根目录找 package.json。

六、第一次部署后先检查这些#

部署成功不等于站点可用。打开 https://<项目名>.pages.dev,按顺序检查:

  1. 首页能否正常渲染;
  2. CSS、JS、字体、图片有没有 404;
  3. 点几个内页,确认路由和相对路径正确;
  4. 打开浏览器控制台,看有没有资源加载失败;
  5. 如果是单页应用,直接访问一个子路由,确认不会返回 404。

单页应用需要在仓库根目录加 _redirects,把未匹配的路径回退到 index.html:

/* /index.html 200

_redirects 和 _headers 都是 Pages 支持的静态配置文件,前者管跳转,后者管响应头。它们只对静态资源生效,不替代后端逻辑。

七、绑定自定义域名#

分两种情况。

域名已经托管在 Cloudflare:进入项目的 Custom domains,添加域名或子域名,Pages 会自动创建解析记录并签发证书。等状态变成 Active 即可。

域名在外部 DNS 服务商:添加一条 CNAME:

blog.example.com → my-blog.pages.dev

根域名(example.com)不能直接加 CNAME,需要 DNS 服务商支持 CNAME 扁平化 / ALIAS,或者把域名 NS 迁到 Cloudflare。绑定期间不要再给同一个主机名加冲突的 A 记录。

HTTPS 由 Cloudflare 自动处理,证书续期不需要手动操作。www 和根域名最好只保留一个主入口,另一个做 301 跳转,避免同一内容出现两个地址。

八、日常发布、预览与回滚#

配置好之后,发布流程就是:

修改代码 → git push → Pages 自动构建 → 生产域名更新

有几个细节值得知道:

  • 生产分支:只有生产分支的提交会更新主域名;
  • 预览部署:推到其他分支会生成独立的预览地址,适合改版前先看效果;
  • 回滚:在 Deployments 里选一个历史部署,执行 Rollback,生产别名会切回那个版本,不需要重新构建;
  • 跳过构建:提交信息里加 [skip ci] 可以跳过本次构建,适合只改文档、不想消耗构建次数的场景(以当前集成为准)。

免费计划每月构建次数有限,频繁推小提交会很快用完。本地把多个修改合成一次提交,比“改一行推一次”更划算。

九、常见问题#

构建失败,但本地正常#

按这个顺序查:Node 版本是否一致、lockfile 是否提交、文件名大小写是否匹配、环境变量是否缺失、原生依赖是否有 Linux 版本。日志里通常会明确指出失败的命令和包名。

部署成功,但页面 404#

先确认输出目录填对。Astro 是 dist,Next.js 静态导出是 out,Hugo 是 public。如果目录填成仓库根目录,Pages 会把源码当静态文件发布,访问时自然找不到页面。

环境变量在代码里读不到#

Pages 的环境变量分“构建时”和“运行时”。构建时注入的变量只在构建阶段可用;前端能读到的变量通常需要框架约定的前缀,例如 Vite 的 VITE_、Astro 的 PUBLIC_。不要把密钥写进这些公开变量里。

自定义域名一直 Pending#

检查 CNAME 是否生效、有没有和现有记录冲突、根域名是否用了不支持的解析方式。DNS 传播需要时间,刚添加就反复刷新没有意义。

图片或样式在本地正常,线上 404#

多半是路径问题:绝对路径 /images/a.png 在子路径部署时会失效;构建工具的 base 配置和实际访问路径不一致也会导致同样的问题。

十、免费额度与真实边界#

Cloudflare Pages 免费计划对个人博客通常够用,但下面这些限制要先知道(数值以控制台当前显示为准):

  • 每月构建次数约 500 次;
  • 单个站点文件数约 20,000 个;
  • 单个文件大小上限约 25 MiB;
  • 单次构建有时间上限,依赖安装过慢会超时;
  • 自定义域名数量有上限;
  • 静态请求不计流量费,但仍受平台公平使用规则约束。

更重要的边界不在数字,而在能力:

  • 它只托管静态文件,不能长期运行 Node.js 服务、定时任务或常驻进程;
  • 需要后端时,要么用 Pages Functions(受 Workers 运行时和调用配额限制),要么接外部数据库 / API;
  • 国内访问不占优势,面向大陆用户的站点仍要单独评估 EdgeOne、腾讯云等方案;
  • 迁移不是零成本,_redirects、_headers、Functions 和绑定关系都会形成平台依赖。

另外,Cloudflare 正在把静态资源托管能力并入 Workers,Pages 仍然可用,但新项目也可以评估 Workers 静态资源路线。本文记录 Pages,是因为它的 Git 集成和预览流程更接近“开箱即用”。

十一、和 EdgeOne Pages 怎么选#

维度Cloudflare PagesEdgeOne Pages
Git 平台GitHub / GitLabGitee / GitHub 等
构建方式推送后自动构建,支持分支预览推送后自动构建,提供预览地址
国内访问一般不占优势免费套餐节点有限,国内加速通常要付费
自定义域名自动签发证书控制台绑定,自动签发证书
回滚历史部署一键回滚以控制台当前能力为准
适合海外访问、GitHub 工作流国内用户、愿意处理备案和付费套餐

一句话:代码在 GitHub、读者在海外,优先 Cloudflare Pages;读者在国内、需要稳定大陆节点,优先评估 EdgeOne 的付费方案。 如果只是临时发一个页面,Cloudflare Drop 或 27c.site 更省事。

十二、上线检查清单#

  • 构建日志全绿,*.pages.dev 能正常打开;
  • 首页、文章页、图片、字体都没有 404;
  • 自定义域名状态为 Active,HTTPS 正常;
  • 推一次测试提交,确认自动构建被触发;
  • 手动回滚一次,确认历史版本可用;
  • 检查本月构建次数和文件数是否够用;
  • 确认环境变量里没有暴露密钥;
  • 如果面向国内用户,单独测一次访问速度。

这套流程真正的收益,是把“部署”变成一次 git push;代价是把构建环境、配额和平台差异交给 Cloudflare。建议先跑通 pages.dev,再绑域名,最后才考虑 Functions 和数据库。顺序反了,排错会复杂很多

Cloudflare Pages 部署静态博客:Git 自动构建、自定义域名与免费额度边界
https://www.violet27chen.com/posts/cloudflare-pages-git/
作者
violet
发布于
2026-11-06
许可协议
CC BY 4.0

评论

评论将由 AI 自动审核;需要人工确认的内容会在审核通过后显示。

正在加载评论……