Skip to content

站点迁移与部署: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(仓库根):

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:truefoo.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)行为差异(已逐项验证):

行为NetlifyCF Static Assets
/foo → foo.htmlpretty URLsauto-trailing-slash ✓
/foo.htmlserve 200307 → /foo(与 sitemap/canonical 一致,更规范)
目录页 /某栏目/200200;无斜杠请求 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 站实例) ​

bash
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 —— 配合 VitePress cleanUrls: true(文件仍输出 .html,站内链接/sitemap 用无后缀地址)
  • not_found_handling: 404-page —— serve VitePress 的 404.html
  • routes 只在主 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. 首绑正式域(有几分钟不可达窗口,挑低峰) ​

  1. wrangler deploy(主 env)
  2. 若报 code 100117("already has externally managed DNS records"):去 dashboard DNS 删除该主机名的旧记录(旧平台的 CNAME / A 记录;www 与裸域各自删)→ 重跑 wrangler deploy
  3. apex+www 双域:routes 写两个 pattern(站点 B 同款:example.org + www.example.org)
  4. 删旧记录到接管完成之间域名不可解析,分钟级
  5. custom_domain 绑定时接管 DNS,证书由 CF 自动签(不再需要灰云签 Let's Encrypt 的旧流程)

6. Access 放行(⚠️ 迁移中最大的坑,务必照做) ​

绑完域 curl 若 302 到 *.cloudflareaccess.com = 被账户 Zero Trust 的通配应用兜住了(没单独配置的子域都会被兜)。三个坑:

  1. 通配兜底:「该子域没配置」≠豁免,恰恰是被拦原因
  2. Allow ≠ 公开:Allow+Everyone 仍弹登录;要完全不弹必须 Bypass(新版 UI 的预设策略 「Make this Worker public」 即等价物)
  3. 域名逐字核对:实测曾把域名敲错一个字母,配置"成功"但永远不生效

新版 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 会话的浏览器自欺) ​

bash
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);Zone Workers Routes: Edit + Zone: Read + DNS: Edit(限 example.com,custom_domain 接管 DNS 用)。勿用 Global API Key
  • GitHub 配置:
位置类型名称值
Environments → site-productionSecretCLOUDFLARE_API_TOKEN限权 Token(见上)
Environments → site-productionVariableCLOUDFLARE_ACCOUNT_IDCF 账户 ID(dash 右侧)
Settings → Secrets and variables → Actions → VariablesVariableSITE_DEPLOY_ENABLEDtrue(未设时 job 跳过,防误部署)
  • 环境 secret 只放 environment,不放 repo 级;Token 值只显示一次,忘了只能 Roll(旧值立即失效,需同步更新 secret)
  • 首次生产部署(custom_domain 首绑)建议先本地 pnpm deploy 完成并处理可能的 DNS 冲突,再打开 SITE_DEPLOY_ENABLED 交给 CI

9. 旧平台收尾(Netlify/Vercel 通用) ​

  1. Pause/断开自动构建(勿删项目——*.netlify.app / *.vercel.app 子域与 301 依赖它活着)
  2. 观察 1—2 周(外链、收录、抓取)
  3. 删仓库内旧平台配置(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 验证