这篇记录我把一个 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子域名)。
先在本地验证一次,不要跳过:
npm cinpm run build构建完成后确认输出目录存在,例如 dist/、out/ 或 public/。如果本地都跑不通,Pages 上大概率也会失败。
三、先把仓库整理成“可被 Linux 构建”的状态
Cloudflare Pages 的构建机是 Linux,本地是 Windows 时,下面几处最容易出问题:
- 提交 lockfile:
package-lock.json、pnpm-lock.yaml或yarn.lock要进仓库,构建时用npm ci才能复现依赖。 - 不要提交
node_modules和dist:构建产物交给 Pages 生成,仓库里只保留源码。 - 注意文件名大小写:Windows 不区分大小写,Linux 区分。
Components/Header.astro和components/header.astro在本地可能都能引用,到构建机就报找不到。 - 固定 Node 版本:Pages 默认版本可能和本地不同,建议在仓库根目录加
.nvmrc,或在控制台设置NODE_VERSION环境变量。填你本地验证过的版本,例如:
22- 原生依赖要留意:
sharp这类带平台二进制的包,本地 Windows 能装不代表 Linux 构建机也能装。遇到构建报错时,先看日志里是哪个包、哪个平台。
四、在 Cloudflare 创建 Pages 项目
控制台入口会随改版变化,按下面的路径找:
Workers & Pages → Create application → Pages → Connect to Git然后:
- 授权 Cloudflare 访问 GitHub;
- 选择要部署的仓库;
- 填写项目名,例如
my-blog; - 选择生产分支,一般是
main; - 填写构建命令和输出目录;
- 保存并部署。
第一次部署会完整跑一遍依赖安装和构建。日志里能看到每一步的耗时,失败时也会停在具体命令上。
五、构建配置对照表
框架预设只是帮你填默认值,提交前仍要自己核对一遍:
| 项目类型 | 构建命令 | 输出目录 | 备注 |
|---|---|---|---|
| Astro | npm run build | dist | 静态输出,默认适配 |
| Vite | npm run build | dist | 注意 base 路径 |
| Next.js 静态导出 | npm run build | out | 需要 output: 'export',不能用服务端功能 |
| Hugo | hugo | public | 确认主题依赖已拉取 |
| 纯 HTML | 留空 | / | 仓库根目录就是站点根目录 |
几个容易踩的坑:
- Next.js 的 SSR / ISR 不能直接跑在 Pages 的纯静态托管上。要用静态导出,或者改用带服务端的方案。
- Vite / Astro 的
base:如果站点部署在子路径,构建时的base要和实际访问路径一致,否则 CSS、JS 会 404。 - Monorepo:如果项目在子目录,构建时要把“根目录”指到对应包,否则 Pages 会在仓库根目录找
package.json。
六、第一次部署后先检查这些
部署成功不等于站点可用。打开 https://<项目名>.pages.dev,按顺序检查:
- 首页能否正常渲染;
- CSS、JS、字体、图片有没有 404;
- 点几个内页,确认路由和相对路径正确;
- 打开浏览器控制台,看有没有资源加载失败;
- 如果是单页应用,直接访问一个子路由,确认不会返回 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 Pages | EdgeOne Pages |
|---|---|---|
| Git 平台 | GitHub / GitLab | Gitee / GitHub 等 |
| 构建方式 | 推送后自动构建,支持分支预览 | 推送后自动构建,提供预览地址 |
| 国内访问 | 一般不占优势 | 免费套餐节点有限,国内加速通常要付费 |
| 自定义域名 | 自动签发证书 | 控制台绑定,自动签发证书 |
| 回滚 | 历史部署一键回滚 | 以控制台当前能力为准 |
| 适合 | 海外访问、GitHub 工作流 | 国内用户、愿意处理备案和付费套餐 |
一句话:代码在 GitHub、读者在海外,优先 Cloudflare Pages;读者在国内、需要稳定大陆节点,优先评估 EdgeOne 的付费方案。 如果只是临时发一个页面,Cloudflare Drop 或 27c.site 更省事。
十二、上线检查清单
- 构建日志全绿,
*.pages.dev能正常打开; - 首页、文章页、图片、字体都没有 404;
- 自定义域名状态为
Active,HTTPS 正常; - 推一次测试提交,确认自动构建被触发;
- 手动回滚一次,确认历史版本可用;
- 检查本月构建次数和文件数是否够用;
- 确认环境变量里没有暴露密钥;
- 如果面向国内用户,单独测一次访问速度。
这套流程真正的收益,是把“部署”变成一次 git push;代价是把构建环境、配额和平台差异交给 Cloudflare。建议先跑通 pages.dev,再绑域名,最后才考虑 Functions 和数据库。顺序反了,排错会复杂很多
如果内容对你有帮助,欢迎用微信或支付宝请我喝杯咖啡 ☕


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