📚 离职知识库

Cloudflare Workers 部署六坑

新域名走 Cloudflare（NS 从原注册商切到 CF），跟原来走 Vercel 的域名并行，互不影响。

#固定信息（示例结构，实际值已脱敏）

项 说明
域名 注册商任意（如 Spaceship），NS 切到 Cloudflare 分配的两个地址
DNS / CDN Cloudflare
Zone ID <ID>
Account ID <ID>
Web Analytics site tag <ID>（zone 级，全站共用）

API Token 走 Cloudflare 通用部署令牌（见《Cloudflare-API令牌治理》），同一账号下多个项目可以共用。

#新项目上线流程（静态站）

#1. 项目里加 wrangler.jsonc

{
  "name": "<项目名>",
  "compatibility_date": "2026-08-01",
  "assets": {
    "directory": "./dist",          // Astro/Vite 是 dist，Next 静态导出是 out
    "not_found_handling": "404-page"
  },
  "observability": { "enabled": true }
}

纯静态站不需要 Worker 脚本，也不需要 Astro 的 Cloudflare adapter，Static Assets 直接托管构建产物。

#2. 构建 + 部署

pnpm build
env -u ALL_PROXY -u all_proxy \
  CLOUDFLARE_API_TOKEN=<KEY> \
  CLOUDFLARE_ACCOUNT_ID=<ID> \
  npx wrangler deploy

部署完先用 https://<项目名>.<账号>.workers.dev 验证。

#3. 绑子域名（Workers Custom Domain）

用 Cloudflare MCP 或 API：

PUT /accounts/{account_id}/workers/domains
{ zone_id: "<ID>",
  hostname: "<子域>.<你的域名>",
  service: "<项目名>", environment: "production" }

Custom Domain 会自动建 DNS 记录、自动签证书、自动橙云代理，不用手动加 CNAME。证书签发约 1～3 分钟，期间访问报 SSL handshake 错误属正常。

#4. 接入 Web Analytics

在站点 HTML 的 <head> 手动注入（Astro Starlight 写在 astro.config.mjs 的 head: 里）：

<script defer src="https://static.cloudflareinsights.com/beacon.min.js"
        data-cf-beacon='{"token": "<ID>"}'></script>

同一个 zone 下所有站共用这个 token，CF 后台按 hostname 分开看。

#5. 别忘了

  • 站点 site / canonical 配置改成新域名，否则 sitemap 和 SEO 还指着旧站。
  • 新站不会自动出现在原有的 Vercel 导航站里（那类导航站通常只扫 Vercel 项目），要手动补录。

#踩过的六坑

  1. wrangler 走 socks 代理必崩。本机若配了 ALL_PROXY=socks5://...，会让 wrangler 的 fetch 直接 TypeError: fetch failed；但完全去掉代理又连不上 CF API。正解是只去掉 ALL_PROXY/all_proxy，保留 HTTP_PROXY/HTTPS_PROXY。

  2. wrangler 的 assets 增量上传会漏文件。改了 HTML 重新 deploy，wrangler 报 "No updated asset files to upload"，线上还是旧内容。清掉项目里的 .wrangler/ 和构建产物目录再重新构建部署，就会正确识别为新增/修改文件。

  3. Workers Assets 有全球传播延迟。deploy 成功后约 20～60 秒内，不同边缘节点可能新旧内容并存（实测首页已更新、子页面还是旧的）。别急着判断部署失败，等一分钟再看。

  4. 改完还要 purge zone 缓存。Workers 响应会被 CF 边缘缓存（cf-cache-status: HIT），Cache-Control: no-cache 请求头也绕不过去。用 POST /zones/{zone_id}/purge_cache {purge_everything: true}。

  5. Web Analytics 的 auto_install 对 Workers 站不生效。建 RUM site 时开 auto_install: true，橙云自动注入的脚本在 Workers Assets 返回的 HTML 上没有出现。改成手动注入 beacon，并把 auto_install 关掉（否则将来生效了会重复计数）。

  6. 新注册域名 60 天内不能转注册商。想让 CF 管 DNS 不需要转注册商，只把 NS 指过来即可，功能一样不少。

#补充经验

  • 国内访问速度要实测。CF 免费版 anycast 在国内不一定比其他 CDN 快，切主域名前先量一遍。走代理的本机测速不代表国内直连的真实情况。
  • 同一项目做迁移期间可以两边并存：老平台版本作为退路，CF 版作为主站（canonical 指向它），确认新版本稳定后再考虑下线旧版或做 301 跳转。

来源：配置信息/openfde.online-Cloudflare部署流程.md（整理于 2026-08-18）

相关笔记