站点迁移与部署:Cloudflare Workers Static Assets(SOP)
沉淀自 2026-10-30 的 Netlify → CF 迁移实战(本仓库 VitePress 站,模式与另一同构站点一致)。适用于任何可构建为纯静态产物的站点:VitePress / Hugo / Next 静态导出等。 模式:wrangler 直传静态目录,零 Worker 脚本,Workers Free 0 成本(静态请求免费不限量、不限带宽;custom_domain 免费)。
脱敏占位:
example.com= zone 主域,share.example.com= 站点子域,「站点 B」= 另一同模式已迁站点。
0. 前置条件(一次性)
- [ ] zone(example.com)与 CF 账户同在
- [ ] 本机
npx wrangler whoami已登录 - [ ] 站点能一条命令构建出静态目录
1. 仓库接入(每站 ~10 分钟)
wrangler.json(仓库根):
{
"name": "<site-name>",
"compatibility_date": "2026-10-13",
"workers_dev": true,
"preview_urls": false,
"assets": {
"directory": "./<产物目录>",
"html_handling": "<按产物形态,见下表>",
"not_found_handling": "404-page"
},
"routes": [
{ "pattern": "<域名>", "custom_domain": true }
],
"env": { "preview": { "name": "<site-name>-preview", "routes": [] } }
}产物形态 → html_handling 对照(实测):
| 站点形态 | 产物形态 | html_handling | 行为 |
|---|---|---|---|
VitePress cleanUrls:true | foo.html 文件 + 无后缀链接 | auto-trailing-slash(默认) | /foo→serve foo.html;.html→307 无后缀 |
| Hugo(默认 prettyurls) | foo/index.html 目录式 | auto-trailing-slash(默认) | /foo/→200;/foo→307 补斜杠 |
| Next 静态导出自带改写 | 自管 | none | 原样 |
与旧平台(Netlify)行为差异(已逐项验证):
| 行为 | Netlify | CF Static Assets |
|---|---|---|
/foo → foo.html | pretty URLs | auto-trailing-slash ✓ |
/foo.html | serve 200 | 307 → /foo(与 sitemap/canonical 一致,更规范) |
目录页 /某栏目/ | 200 | 200;无斜杠请求 307 补斜杠(sitemap 即带斜杠形式) |
| 中文编码路径 | ✓ | ✓(已逐页验证中文正文页) |
踩坑:compatibility_date 勿写当天——wrangler 4.150.0 的 workerd 上限 2026-10-13,写新日期 wrangler dev 起不来(纯静态无行为差异,固定 2026-10-13)。
其余:pnpm/npm add -D wrangler@4.150.0(锁版本)、package.json 加 deploy/deploy:preview scripts、.gitignore 加 .wrangler/。
2. 本仓库部署速查(share 站实例)
pnpm deploy:preview # build + 部署 <site-name>-preview.<子域>.workers.dev(验证用,不绑域)
pnpm deploy # build + 部署生产 worker 并绑定 share.example.com(custom_domain)
npx wrangler dev # 本地同 runtime 验证(默认 8787)配置要点(wrangler.json):
assets.directory: ./.vitepress/dist—— VitePress 产物(注意在仓库根,不是 docs/ 下)html_handling: auto-trailing-slash—— 配合 VitePresscleanUrls: true(文件仍输出.html,站内链接/sitemap 用无后缀地址)not_found_handling: 404-page—— serve VitePress 的404.htmlroutes只在主 env 绑share.example.com(custom_domain);env.preview无 routes、独立 worker 名
3. 本地验证(npx wrangler dev,绕开 Access 干扰)
逐项 curl 检查:首页 200、任一内页无后缀/目录形式 200、带 .html 或缺斜杠时 307 规范化、404 页(状态 404+自定义页)、/sitemap.xml、/llms.txt、favicon、中文编码路径。
4. preview 上云
pnpm deploy:preview → *.workers.dev。被 Cloudflare Access 拦(302 登录)属预期,不影响正式域,目检用浏览器(有 Access 会话)或干脆只靠第 3 步本地验证。
5. 首绑正式域(有几分钟不可达窗口,挑低峰)
wrangler deploy(主 env)- 若报 code 100117("already has externally managed DNS records"):去 dashboard DNS 删除该主机名的旧记录(旧平台的 CNAME / A 记录;www 与裸域各自删)→ 重跑
wrangler deploy - apex+www 双域:routes 写两个 pattern(站点 B 同款:
example.org+www.example.org) - 删旧记录到接管完成之间域名不可解析,分钟级
- custom_domain 绑定时接管 DNS,证书由 CF 自动签(不再需要灰云签 Let's Encrypt 的旧流程)
6. Access 放行(⚠️ 迁移中最大的坑,务必照做)
绑完域 curl 若 302 到 *.cloudflareaccess.com = 被账户 Zero Trust 的通配应用兜住了(没单独配置的子域都会被兜)。三个坑:
- 通配兜底:「该子域没配置」≠豁免,恰恰是被拦原因
- Allow ≠ 公开:Allow+Everyone 仍弹登录;要完全不弹必须 Bypass(新版 UI 的预设策略 「Make this Worker public」 即等价物)
- 域名逐字核对:实测曾把域名敲错一个字母,配置"成功"但永远不生效
新版 UI 路径:Zero Trust → Access → Applications → Add an application → Self-hosted and private → 目的地类型选 Public DNS(公网域名;若该应用就是给某 Worker 公开可选 Workers)→ 填精确域名(逐字核对!) → 策略选 Make this Worker public(或手动 Action=Bypass + Include=Everyone) → 保存。通配应用不动,其它子域继续受保护。
注:*.workers.dev 默认也被账户 Access 保护,匿名 curl 302 属预期;正式域走 zone 配置公开服务,不受影响。
7. 匿名全站验证(必须 curl,别用带 Access 会话的浏览器自欺)
for p in / /sitemap.xml /llms.txt /<代表性内页>; do
curl -s -o /dev/null -w "$p -> %{http_code}\n" "https://share.example.com$p"
done # 全 200;404 用 /no-such-page 验证8. CI 自动部署(push 即发布)
- workflow:
.github/workflows/deploy-site.yml(build + deploy + 冒烟 200 检查;concurrency串行防重入;workflow_dispatch支持手动重跑;pnpm 版本由packageManager字段固定) - 限权 Token(CF → My Profile → API Tokens → Custom):Account
Workers Scripts: Edit(限本账户,勿选 All accounts);ZoneWorkers Routes: Edit+Zone: Read+DNS: Edit(限 example.com,custom_domain 接管 DNS 用)。勿用 Global API Key - GitHub 配置:
| 位置 | 类型 | 名称 | 值 |
|---|---|---|---|
Environments → site-production | Secret | CLOUDFLARE_API_TOKEN | 限权 Token(见上) |
Environments → site-production | Variable | CLOUDFLARE_ACCOUNT_ID | CF 账户 ID(dash 右侧) |
| Settings → Secrets and variables → Actions → Variables | Variable | SITE_DEPLOY_ENABLED | true(未设时 job 跳过,防误部署) |
- 环境 secret 只放 environment,不放 repo 级;Token 值只显示一次,忘了只能 Roll(旧值立即失效,需同步更新 secret)
- 首次生产部署(custom_domain 首绑)建议先本地
pnpm deploy完成并处理可能的 DNS 冲突,再打开SITE_DEPLOY_ENABLED交给 CI
9. 旧平台收尾(Netlify/Vercel 通用)
- Pause/断开自动构建(勿删项目——
*.netlify.app/*.vercel.app子域与 301 依赖它活着) - 观察 1—2 周(外链、收录、抓取)
- 删仓库内旧平台配置(
netlify.toml/vercel.json)→ 下线旧项目(旧子域 301 副本随之消失,外链影响通常可忽略;回滚只能重走接入流程)
10. 实测坑速查
| 坑 | 症状 | 解 |
|---|---|---|
| compat date 超限 | wrangler dev 起不来 | 固定 2026-10-13 |
| DNS 冲突 | deploy 报 100117 | 删旧记录重跑 |
| 正式域被拦 | 全站 302 Access 登录 | 见 §6,Bypass/Make public |
| Allow 无效 | 设了还拦 | 改 Bypass 或用预设 |
| 域名笔误 | 配置成功但不生效 | 逐字核对 |
| CI 冒烟红 | curl 非 200 | 先查 Access,再查产物 |
| pnpm store 变更 | pnpm add 报 store 不一致 | rm -rf node_modules && pnpm install |
| preview 被拦 | workers.dev 302 | 预期,用 wrangler dev 验证 |