#先分清三个东西
Cloudflare 上现在有三条路径能把静态文件推到公网,名字很像,行为差别不小:
| 方式 | 触发方式 | 适合场景 | 注意点 |
|---|---|---|---|
| Pages + Git 集成 | push 到仓库自动构建 | 长期维护的博客 | 构建环境在 Cloudflare,需要 package-lock.json |
| Pages 直接上传 | wrangler pages deploy |
临时预览、无 Git | 每次上传是完整快照 |
| Workers 静态资源 | wrangler deploy |
需要 Worker 逻辑同时存在 | 按 Workers 计费模型走 |
纯静态博客我推荐第一种。原因不是它更快,而是它把你的发布流程钉在了 Git 上——任何一次线上变化都能追溯到某个 commit,这比任何部署工具的仪表盘都可靠。
#构建设置只有三行
Build command: npm run build
Build output dir: dist
Root directory: /
但要注意两件事:
Node 版本。 Cloudflare 默认版本可能比你本地低。我在 package.json 里显式声明:
{
"engines": { "node": ">=20" }
}
如果项目里用到 node:fs/promises 的新 API 或者 ESM 的 import.meta.dirname,版本不一致会在构建日志里报一堆莫名其妙的 undefined is not a function。
必须提交 lockfile。 有 package-lock.json 时它跑 npm ci(快、可复现),没有时跑 npm install(可能装到新版本)。后者在依赖范围写 ^ 的时候,随时可能因为某个次版本更新把构建搞挂。
#坑一:文件名大小写
这是最容易在生产环境才炸的问题。本地 Windows 或 macOS 的文件系统默认不区分大小写,Cover.svg 和 cover.svg 是同一个文件。Linux 构建环境区分,于是:
GET /assets/Covers/hero.svg 404
排查半天发现代码里写的是 Covers,文件名是 covers。建议在本地就养成全小写命名的习惯,并且给构建脚本加一道检查:
// 构建时校验:所有引用路径必须与实际文件完全一致
const files = new Set(walk(path.join(DIST, 'assets')).map(f => f.replace(DIST, '')));
const html = fs.readFileSync(path.join(DIST, 'index.html'), 'utf8');
const refs = [...html.matchAll(/(?:src|href)="(\/assets\/[^"]+)"/g)].map(m => m[1]);
const missing = refs.filter(r => !files.has(r));
if (missing.length) throw new Error(`引用了不存在的资源: ${missing.join(', ')}`);
十几行代码,能省掉一次线上事故。
#坑二:缓存把新版本挡住了
默认情况下 Cloudflare 对静态资源会做边缘缓存。带 hash 的文件名(app.a1b2c3.js)可以放心 immutable,但 index.html 绝对不能:
/assets/*
Cache-Control: public, max-age=31536000, immutable
/index.html
Cache-Control: public, max-age=0, must-revalidate
_headers 文件放在输出目录根部就会生效,不需要任何配置。注意一个细节:规则按从上到下的顺序匹配,第一条命中即停。如果你先写了 /* 再写 /assets/*,后者永远不会生效。
我因为这个问题盯着「已经改了但浏览器还是旧的」盯了二十分钟。
#坑三:404 与 SPA 回退
纯静态站不需要 SPA 回退。但如果你用的是 Pages 的 Git 集成,要确认它找到了 404.html:
- Pages:输出目录里有
404.html会自动用于 404 响应; - Workers 静态资源:需要在
wrangler.jsonc里显式声明。
{
"name": "code-and-beyond",
"compatibility_date": "2026-11-01",
"assets": {
"directory": "./dist",
"not_found_handling": "404-page"
}
}
not_found_handling 还有两个值:single-page-application(所有未命中回退到 index.html)和 none(直接返回 404 空页)。博客选 404-page。
#坑四:重定向的三种写法
_redirects 是最省事的方式,但语法有几个陷阱:
# 正确:状态码必须是 301 或 302
/feed /rss.xml 301
# 通配符::slug 捕获一段,* 捕获剩余全部
/posts/:slug /posts/:slug.html 301
# 错误示范:指向外站时 status 可省略,默认 302
还有一条容易忘:_redirects 最多 2000 条静态规则,超出部分不生效且不报错。博客用不到,但如果你在做老站迁移,这就是个定时炸弹。
#坑五:自定义域名的 DNS 状态
绑定域名后,Cloudflare 会显示 Active 或 Pending。如果是 Pending,基本是两个原因:
- 域名的 NS 还没指向 Cloudflare;
- CNAME 记录被别的记录占了(
blog子域已有一条 A 记录)。
第二种情况最容易卡住。删掉冲突记录,等一分钟,重新添加。
顺带一句:开了 Universal SSL 之后仍然要等证书签发,新域名有时要十几分钟。这段时间访问会报证书错误,不是配置错了。
#一份可以直接抄的发布流程
# 1. 本地预览
npm run dev
# 2. 构建 + 检查产物
npm run build
du -sh dist && find dist -name "*.html" | wc -l
# 3. 部署(Workers 静态资源方式)
npx wrangler deploy
# 4. 验证响应头
curl -sI https://blog.example.com/ | grep -i cache-control
如果走 Git 集成,第 3 步换成 git push。我倾向于前一种:手动部署让我有机会在发布前看一眼产物大小。有一次误把几十张未压缩的 PNG 提交进去,dist 从 2 MB 涨到 40 MB,手动那一眼救了它。
#最后
Cloudflare 的免费额度对个人博客来说绰绰有余:无限请求、无限带宽、每天 500 次构建。真正需要操心的从来不是额度,而是上面这些「文档里写了但你不一定会读到」的细节。
部署这件事,理想状态是你永远不需要想起它。要达到这个状态,前期多花两小时把边界条件理清楚,比事后半夜被 404 叫醒划算得多。