项目：用 Pages 搭一个长期免费的个人博客
博客是最适合长期免费托管的形态：内容更新频率低、页面数量可控、读者只看不写。Pages 免费档给 500 次构建/月、2 万个文件、单文件 25 MiB，静态请求和带宽不计费，也不占 Workers 请求额度。做完这篇你会有一个自动化流程：推一次 Git，几分钟后文章上线；以及一套不会因为"随手改个字"就把构建额度烧完的习惯。
这次没有 Zone 与 Pages 写权限，wrangler pages project create 和自定义域绑定都没有实机执行，步骤依据官方文档。平台入门见 67-pages-getting-started.md，框架细节见 71-static-site-astro-hugo.md。
1. 先选框架
| 框架 | 构建命令 | 输出目录 | 适合 |
|---|---|---|---|
| Hugo | hugo --minify | public | 文章多、构建快，单二进制无依赖 |
| Astro | npm run build | dist | 想混一点交互组件 |
| VitePress | npm run docs:build | .vitepress/dist | 文档型、侧边栏结构强 |
| 纯 HTML | 无 | / | 十几页，不想碰 Node |
Pages 对主流框架有预设，选完框架构建命令会自动填。用 Hugo 的话注意版本：Pages 构建镜像里的 Hugo 版本可能比你本地旧，hugo.toml 里用了新版语法会在云端报错、本地却正常。锁版本的办法是在仓库根目录放 .nvmrc 或在构建命令里直接下载指定版本。
2. 三条部署路线
Git 集成是主线：仓库连上 Pages，每次 push 触发构建，PR 生成一个预览 URL。Direct Upload 适合没有 Git 仓库的场景，用 wrangler pages deploy 从本地推文件，构建在本地做。第三种是 CI 里跑 wrangler pages deploy dist --project-name=blog，适合已经在用 GitHub Actions 的仓库。
# 本地构建后直传，绕过 Pages 的构建环境
npm run build
npx wrangler pages deploy dist --project-name=my-blogDirect Upload 与 Git 集成不能混用在同一个项目上。先用了直传，后来想接 Git，得新建项目。
3. 构建参数
| 配置项 | 值 | 说明 |
|---|---|---|
| Framework preset | Hugo / Astro / None | 决定默认构建命令 |
| Build command | hugo --minify | 留空表示不需要构建 |
| Build output directory | public | 要与产物目录一致 |
| Root directory | 仓库子目录 | 博客放在 monorepo 子目录时填 |
| 环境变量 | HUGO_VERSION=0.140.0 | 锁工具版本 |
一个高频失败原因：构建输出目录填错。Pages 构建成功但站点 404，通常是产物在 dist 而配置写了 public，部署上去的是一堆源码。
4. 自定义域
域名接入 Cloudflare 并处于 Active 状态后，在 Pages 项目的 Custom domains 里加 blog.example.com，CNAME 会自动建好。裸域（example.com）也支持，走的是 CNAME flattening，不需要额外操作。证书自动签发，通常几分钟内生效。
预览部署默认给每个分支一个 <branch>.<project>.pages.dev 的地址。如果博客有草稿不想被搜索引擎抓到，预览域要单独加一条 X-Robots-Tag: noindex，或者在 _headers 文件里统一处理：
/*
X-Robots-Tag: noindex这个文件只在预览环境生效的写法是把 _headers 放进入口之外的目录，更简单的做法是预览分支单独配置。
5. 额度的真实边界
500 次构建/月，平均每天 16 次。写博客完全够，但如果仓库里有自动提交（比如定时抓取生成日报、或每次 CI 都往仓库写文件），很容易在半个月内烧完。额度用完后当月不能再构建，站点继续在线，只是不能更新。
单次构建 20 分钟超时，免费档同时只能跑 1 个构建。文章上千篇、图片没做压缩的站点，构建时间会逼近这个上限。把图片放 R2 或图床（见 98-project-image-host-r2.md），构建只处理文本，时间能压到一分钟内。
预览部署同样消耗构建次数。每个分支的每次提交都会触发一次构建，十个分支并行开发时，一次合并就可能产生十几次构建记录。习惯是：长期分支留两三个，功能分支用完即删，别让废弃分支一直挂在项目里。
2 万个文件是硬上限。每篇文章一个 HTML 加上标签页、分页、静态资源，一篇占 3 到 5 个文件的话，四千篇左右就到顶。个人博客很难触到，但如果给每篇文章生成多语言版本、多个尺寸封面图，文件数会膨胀得比想象快。
6. 常见问题
博客要不要上 Workers？纯静态不需要，Pages 直接发文件更快也更省额度。需要评论、搜索、访问统计接口时再加一个 Worker 或 Pages Functions，见 68-pages-functions.md。
换域名会不会丢流量？Pages 的自定义域可以加多个，旧域名 301 到新域名即可。老站点的外链权重靠 301 传递，别直接删项目。
构建失败但本地正常怎么办？先看构建日志里的 Node 版本和框架版本，再看环境变量有没有漏配。本地 npm run build 前先 rm -rf node_modules && npm ci，能复现大部分"云端才报错"的问题。
小结
Pages 对博客的适配度很高：构建次数够用、文件数够用、流量不计费、证书自动签。整套成本是零，代价是要接受"静态"这个前提——评论、搜索、点赞这些都需要额外接一个服务。
真正决定体验的是构建流水线而不是托管平台。把图片外置、锁住框架版本、构建输出目录配对，这三件事做好，博客就能长期稳定地免费跑下去。部署完成后的性能与成本复核见 105-performance-cost-checklist.md，全系列索引见 106-roadmap-index.md。
数据来源与检索时间
检索时间 2026-11-10。
| 来源 | URL | 对应数据 |
|---|---|---|
| Pages 限额 | https://developers.cloudflare.com/pages/platform/limits/ | 500 构建/月、1 个并发构建、20 分钟超时、20,000 文件、单文件 25 MiB |
| Pages 构建配置 | https://developers.cloudflare.com/pages/configuration/build-configuration/ | 构建命令、输出目录、根目录、环境变量 |
| Pages 自定义域 | https://developers.cloudflare.com/pages/configuration/custom-domains/ | CNAME 自动创建、裸域 flattening、证书签发 |
核验说明
- 文档核对：构建次数、并发数、超时、文件数与单文件大小来自 Pages Limits 页面（2026-11-10 抓取成功）。
- 未做：Pages 项目创建、Git 集成、构建、自定义域绑定均未执行——当前 Token 无 Pages 写权限。文中"构建成功但站点 404"等内容来自构建配置文档的说明与常见故障模式，不是本账号的实测记录。
- 额度边界（多少篇文章会撞上 2 万文件）为按每篇 3–5 个文件推算，未实测。