#先分清三个东西

Cloudflare 上现在有三条路径能把静态文件推到公网,名字很像,行为差别不小:

方式 触发方式 适合场景 注意点
Pages + Git 集成 push 到仓库自动构建 长期维护的博客 构建环境在 Cloudflare,需要 package-lock.json
Pages 直接上传 wrangler pages deploy 临时预览、无 Git 每次上传是完整快照
Workers 静态资源 wrangler deploy 需要 Worker 逻辑同时存在 按 Workers 计费模型走

纯静态博客我推荐第一种。原因不是它更快,而是它把你的发布流程钉在了 Git 上——任何一次线上变化都能追溯到某个 commit,这比任何部署工具的仪表盘都可靠。

#构建设置只有三行

CODE
Build command:      npm run build
Build output dir:   dist
Root directory:     /

但要注意两件事:

Node 版本。 Cloudflare 默认版本可能比你本地低。我在 package.json 里显式声明:

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 构建环境区分,于是:

CODE
GET /assets/Covers/hero.svg 404

排查半天发现代码里写的是 Covers,文件名是 covers。建议在本地就养成全小写命名的习惯,并且给构建脚本加一道检查:

JavaScript
// 构建时校验:所有引用路径必须与实际文件完全一致
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 绝对不能:

CODE
/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 里显式声明。
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 是最省事的方式,但语法有几个陷阱:

CODE
# 正确:状态码必须是 301 或 302
/feed        /rss.xml   301

# 通配符::slug 捕获一段,* 捕获剩余全部
/posts/:slug  /posts/:slug.html  301

# 错误示范:指向外站时 status 可省略,默认 302

还有一条容易忘:_redirects 最多 2000 条静态规则,超出部分不生效且不报错。博客用不到,但如果你在做老站迁移,这就是个定时炸弹。

#坑五:自定义域名的 DNS 状态

绑定域名后,Cloudflare 会显示 Active 或 Pending。如果是 Pending,基本是两个原因:

  1. 域名的 NS 还没指向 Cloudflare;
  2. CNAME 记录被别的记录占了(blog 子域已有一条 A 记录)。

第二种情况最容易卡住。删掉冲突记录,等一分钟,重新添加。

顺带一句:开了 Universal SSL 之后仍然要等证书签发,新域名有时要十几分钟。这段时间访问会报证书错误,不是配置错了。

#一份可以直接抄的发布流程

Bash
# 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 叫醒划算得多。