Cloudflare Workers Smart Placement 排错完全指南:常见错误、性能陷阱与架构避坑(cloudflare-deploy 技能实战)

原创2026-09-12 15:23:011,462 阅读
文章标签:AI 技能开发工具人工智能提示工程代码评审

Cloudflare Workers Smart Placement 排错完全指南:常见错误、性能陷阱与架构避坑(cloudflare-deploy 技能实战)

本文基于 GitHub 推荐项目精选(skills4 / skills)仓库中的 cloudflare-deploy 技能库 所收录的 Smart Placement 排错文档整理而成。Smart Placement 是 Cloudflare Workers 的自动工作负载放置优化功能:它不再默认把 Worker 调度到离最终用户最近的边缘节点,而是通过分析全球网络上的请求耗时数据,将请求转发到更靠近后端基础设施(数据库、内部 API)的数据中心,从而降低整体请求延迟。本文聚焦 Smart Placement 上线前后最常见的错误(INSUFFICIENT_INVOCATIONS、UNSUPPORTED_APPLICATION、指标缺失、cf-placement 头缺失)、Pages/Assets 静态资源性能劣化、单体全栈 Worker 架构陷阱、RPC 方法不受影响这一关键限制,以及禁用与"何时不该用"的判断清单,帮助你在 cloudflare-deploy 技能驱动下完成可验证的部署与排错。

前置背景:本仓库中的 Smart Placement 参考集

在深入排错之前,先了解本仓库中围绕 Smart Placement 组织的四份参考文档,它们共同构成了完整的知识闭环:

在 SKILL.md 的决策树中,Smart Placement 被定位为"优化到后端基础设施的延迟(而非面向用户的延迟)",这一定位正是后续所有 gotcha 的根源:Smart Placement 的目标是降低后端通信延迟,任何与这一目标相悖的场景都会产生问题。

一、常见错误:四个高频报错/现象的排查

1. INSUFFICIENT_INVOCATIONS

原因:流量不足,Smart Placement 无法积累足够样本来分析并做出放置决策。

解决方案(来自 gotchas.md 原文,全部保留):

  • 确保 Worker 能收到持续、稳定的全球流量;
  • 等待更长时间——分析最长需要 15 分钟;
  • 从多个全球地理位置发送测试流量(单一地域的流量无法代表全球拓扑);
  • 检查 Worker 是否具备 fetch 事件处理器(没有 fetch handler 的 Worker 根本不参与 Smart Placement 分析)。

从 api.md 的 PlacementStatus 类型可以看出该状态的语义:

type PlacementStatus =
  | undefined  // 尚未被分析
  | 'SUCCESS'  // 优化成功
  | 'INSUFFICIENT_INVOCATIONS'  // 流量不足,无法做出放置决策
  | 'UNSUPPORTED_APPLICATION';  // 使 Worker 变慢(已回退)

当状态为 INSUFFICIENT_INVOCATIONS 时,Worker 始终运行在默认的、离用户最近的边缘位置,也就是说此时只是"尚未优化",而非"优化失败"。

2. UNSUPPORTED_APPLICATION

原因:Smart Placement 分析后认为它让 Worker 变慢而非变快,系统回退到边缘运行。

常见原因(文档完整列举):

  • Worker 不做后端调用(本来在边缘跑就最快);
  • 后端调用已被缓存(此时网络延迟对用户更重要,靠近用户反而更好);
  • 后端服务本身在全球有良好的分布(不存在"单一最优位置");
  • Worker 只提供静态资源或 Pages 内容。

解决方案:

  • 显式禁用 Smart Placement:{ "placement": { "mode": "off" } };
  • 重新评估该 Worker 是否真的能从 Smart Placement 获益;
  • 考虑引入缓存策略以减少后端调用次数;
  • 对于 Pages/Assets 类 Worker,改为拆分出独立的、启用 Smart Placement 的后端 Worker。

文档强调 UNSUPPORTED_APPLICATION 是罕见状态(在 api.md 中标注为 <1% 的 Worker),但一旦出现:放置决策被回退、Worker 始终运行在边缘、在重新部署之前不会被再次分析。也就是说,修复问题后必须重新部署一次才能触发重新评估。

3. "No request duration metrics"(没有请求耗时指标)

原因:Smart Placement 未启用、启用后时间不足、流量不足,或分析尚未完成。

解决方案:

  • 确认配置中已启用 Smart Placement("placement": { "mode": "smart" });
  • 部署后等待 15 分钟以上;
  • 验证 Worker 有足够的流量;
  • 检查 placement_status 是否为 SUCCESS。

对应的指标查看路径(来自 api.md):

Workers & Pages → [Your Worker] → Metrics → Request Duration

该指标以直方图对比两路流量的请求耗时:启用 Smart Placement 的 99% 流量 vs 作为基线的 1% 流量。请务必区分"请求耗时"与"执行耗时":请求耗时是从请求到达至响应返回的总时间(包含网络延迟),执行耗时是 Worker 代码实际执行的时间(不含网络等待)——衡量 Smart Placement 收益应看请求耗时。

4. cf-placement header missing(响应头缺失)

原因:Smart Placement 未启用、该 Beta 功能已被移除,或 Worker 尚未完成分析。

解决方案:确认 Smart Placement 已启用、等待分析完成(约 15 分钟)、检查 Beta 功能在当前版本是否仍可用。

cf-placement 是 Cloudflare 在响应头中加入的路由决策标识(api.md):

"cf-placement: remote-LHR"  // Smart Placement 将请求路由到了伦敦
"cf-placement: local-EWR"   // 停留在纽瓦克边缘节点

格式为 {placement-type}-{IATA-code}:remote-* 表示被 Smart Placement 路由到远端位置,local-* 表示停留在默认边缘位置,IATA 码是距离数据中心最近的机场代码。注意该头是 Beta 功能,可能在 GA 前被移除,代码中不要对它做硬依赖。

你还可以在 Worker 代码里读取该头用于诊断(api.md 示例):

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const placementHeader = request.headers.get('cf-placement');

    if (placementHeader?.startsWith('remote-')) {
      const location = placementHeader.split('-')[1];
      console.log(`Smart Placement routed to ${location}`);
    } else if (placementHeader?.startsWith('local-')) {
      const location = placementHeader.split('-')[1];
      console.log(`Running at edge location ${location}`);
    }

    return new Response('OK');
  }
} satisfies ExportedHandler<Env>;

二、Pages/Assets + Smart Placement 的性能劣化(最常见、影响最大的误配置)

问题:当 Smart Placement 与 run_worker_first = true 同时启用时,静态资源的加载速度会慢 2~5 倍。

原因:Smart Placement 会把所有请求(包括 HTML、CSS、JS、图片等静态资源)路由到远端位置。而静态内容永远应该由离用户最近的边缘节点提供。把静态资源路由到远端,等于主动放弃了边缘缓存与就近交付的全部优势。

解决方案:拆分为独立 Worker,或直接禁用 Smart Placement:

// ❌ BAD - 静态资源被路由离开用户
{
  "name": "pages-app",
  "placement": { "mode": "smart" },
  "assets": { "run_worker_first": true }
}

// ✅ GOOD - 静态资源留在边缘,API 被优化
// frontend/wrangler.jsonc
{
  "name": "frontend",
  "assets": { "run_worker_first": true }
  // 没有 placement 字段 - 保持在边缘
}

// backend/wrangler.jsonc
{
  "name": "backend-api",
  "placement": { "mode": "smart" }
}

这是 Smart Placement 最常见、影响最大的误配置之一。configuration.md 给出了按优先级排列的三种解决方案:

  1. (推荐)拆分为独立 Worker:前端留在边缘,后端启用 Smart Placement;
  2. 将 "mode" 显式设为 "off" 以禁用 Smart Placement;
  3. 设置 assets.run_worker_first = false(先服务静态资源,静态内容请求绕过 Worker)。

核心结论(configuration.md 原话):永远不要对以 run_worker_first = true 提供静态资源的 Worker 启用 Smart Placement。

三、单体全栈 Worker:前后端逻辑混在一起

问题:前端与后端逻辑位于同一个 Worker 中,且启用了 Smart Placement。

原因:Smart Placement 优化的是后端延迟,但代价是用户可见的响应时间变长。单体 Worker 无法"既靠近用户又靠近数据库"——它只能二选一。

解决方案:拆分为两个 Worker,前端显式禁用、后端启用:

// frontend/wrangler.jsonc
{
  "name": "frontend",
  "placement": { "mode": "off" },  // 显式声明:留在边缘
  "services": [{ "binding": "BACKEND", "service": "backend-api" }]
}

// backend/wrangler.jsonc
{
  "name": "backend-api",
  "placement": { "mode": "smart" },
  "d1_databases": [{ "binding": "DB", "database_id": "xxx" }]
}

这与 README.md 中的推荐架构模式完全一致:

User → Frontend Worker (边缘,靠近用户)
         ↓ Service Binding
       Backend Worker (启用 Smart Placement,靠近 DB/API)
         ↓
       Database/Backend Service

采用这种"前后端拆分 + fetch 型 Service Binding"的架构(详见 patterns.md),前端保持快速响应,后端延迟被优化,两全其美。

四、本地开发的困惑:wrangler dev 下 Smart Placement 不生效

问题:在 wrangler dev 中测试时发现 Smart Placement 不起作用。

解释:Smart Placement 只在生产部署中生效,本地开发(local simulation)不会执行流量分析与智能路由。

解决方案:在 staging 环境测试:

wrangler deploy --env staging

注意这与 Wrangler 的本地/远程执行语义一致(参见 wrangler/gotchas.md):wrangler dev 默认是本地模拟(快但精度有限),wrangler dev --remote 才是生产级远端执行。Smart Placement 依赖 Cloudflare 全球网络的真实流量数据,因此无论如何都要通过 wrangler deploy 到实际环境(或至少 --env staging)才能观测其行为。

五、基线流量与分析时间

基线流量:Smart Placement 会自动将 1% 的请求以未优化方式路由,作为性能对比的基线(这部分流量不享受智能路由)。这是预期行为,不是故障——在 Metrics 的请求耗时直方图里,你会看到"带 Smart Placement(99% 流量)"与"不带 Smart Placement(1% 基线)"两条曲线,正是靠它们对比来判断收益。

分析时间:最长 15 分钟。分析期间 Worker 运行在边缘。请持续监控 placement_status:

# 通过 API 查询放置状态(来自 api.md / README.md)
curl -H "Authorization: Bearer $TOKEN" \
  https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/services/$WORKER_NAME \
  | jq .result.placement_status

如何解读指标对比(api.md 的判定表):

指标对比 解读 行动
带 Smart < 不带 Smart Smart Placement 在帮忙 保持启用
带 Smart ≈ 不带 Smart 影响中性 考虑禁用以释放资源
带 Smart > 不带 Smart Smart Placement 在拖累性能 用 mode: "off" 禁用

六、RPC 方法不受影响(关键限制)

问题:在后端启用了 Smart Placement,但 RPC 调用依然很慢。

原因:Smart Placement 只影响 fetch handler。RPC 方法(基于 WorkerEntrypoint 的 Service Bindings)永远不会被影响。

为什么:RPC 调用绕过了 fetch handler——Smart Placement 只能路由 fetch 请求。

解决方案:改用基于 fetch 的 Service Binding:

// ❌ RPC - Smart Placement 完全无效
export class BackendRPC extends WorkerEntrypoint {
  async getData() {
    // 始终运行在边缘
    return await this.env.DATABASE.prepare('SELECT * FROM table').all();
  }
}

// ✅ Fetch - Smart Placement 生效
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // 启用 Smart Placement 后,运行在靠近 DATABASE 的位置
    const data = await env.DATABASE.prepare('SELECT * FROM table').all();
    return Response.json(data);
  }
}

configuration.md 对这一限制的界定非常严格,列出了完全不受影响的对象:

  • RPC 方法(基于 WorkerEntrypoint 的 Service Bindings);
  • 具名入口(除 default 外的其他 export);
  • 没有 fetch handler 的 Worker;
  • Queue consumers、scheduled handlers 等其他事件类型。

文档给出的结论是:如果后端逻辑使用 RPC 方法,Smart Placement 无法优化这些调用,必须改用 fetch 型模式才能生效(或用一个带 fetch handler 的包装 Worker 去调用后端 RPC,但会引入额外延迟)。patterns.md 同样用"RPC vs Fetch - CRITICAL"的措辞强调了这一点。这也解释了为什么文档要求"检查 Worker 有 fetch event handler"是启用 Smart Placement 的前提之一。

相关但容易混淆:Smart Placement 也不控制 Durable Objects 的运行位置(DO 始终运行在其指定区域)。Smart Placement 影响的只是"协调 Worker 的 fetch handler 运行在哪里"——当协调 Worker 需要向多个 DO 发起调用时,把它放在靠近 DO 区域的位置才有意义(详见 patterns.md 的 Durable Objects 章节)。

七、启用要求与硬性限制

启用要求

  • Wrangler 2.20.0+(必需);
  • 持续的多地域流量(单一地域流量不足以支撑分析);
  • 只影响 fetch handler——RPC 方法与具名入口不受影响;
  • 可用性:所有 Workers 套餐(Free、Paid、Enterprise)。

限制速查表

资源/限制 数值 说明
分析时间 最长 15 分钟 启用后开始
基线流量 1% 不经过优化直接路由
最低 Wrangler 版本 2.20.0+ 必需
流量要求 多地域 需持续稳定

八、如何禁用 Smart Placement

{ "placement": { "mode": "off" } }  // 显式禁用
// 或者直接删除 "placement" 字段(效果完全相同)

两种方式的行为完全一致:Worker 运行在离用户最近的边缘位置。

配置层面的取值说明(configuration.md 中的模式表):

模式 行为
"smart" 启用 Smart Placement,基于流量分析自动优化
"off" 显式禁用,始终运行在离用户最近的边缘
未指定 默认行为,运行在离用户最近的边缘(与 "off" 相同)

校验规则(重要):mode 与显式放置字段(region、host、hostname)互斥,不能同时使用:

// ✅ 合法 - Smart Placement
{ "placement": { "mode": "smart" } }

// ✅ 合法 - 显式放置(另一个独立功能)
{ "placement": { "region": "us-east1" } }

// ❌ 非法 - 二者不可混用
{ "placement": { "mode": "smart", "region": "us-east1" } }

九、何时不该启用 Smart Placement(避坑清单)

以下场景不会受益,甚至可能性能更差,不要启用:

  • 只提供静态内容或缓存响应的 Worker;
  • 没有显著后端通信的 Worker;
  • 纯边缘逻辑(认证检查、重定向、简单转换);
  • 没有 fetch 事件处理器的 Worker;
  • 以 run_worker_first = true 运行静态资源的 Pages/Assets Worker;
  • 使用 RPC 方法而非 fetch handler 的 Worker。

对照 README.md 的决策树可以快速自检:

Worker 是否有 fetch handler?
├─ 否 → Smart Placement 不生效(跳过)
└─ 是
   │
   是否做多次后端调用(DB/API)?
   ├─ 否 → 不要启用(无帮助)
   └─ 是
      │
      后端是否地理集中?
      ├─ 否(全球分布)→ 可能无帮助
      └─ 是或不确定
         │
         是否以 run_worker_first=true 提供静态资源?
         ├─ 是 → 不要启用(会伤害性能)
         └─ 否 → 启用 Smart Placement
            │
            15 分钟后检查 placement_status
            ├─ SUCCESS → 持续监控指标
            ├─ INSUFFICIENT_INVOCATIONS → 需要更多流量
            └─ UNSUPPORTED_APPLICATION → 禁用(正在伤害性能)

反面场景的典型表现:当 Smart Placement 适得其反时,通常是因为——Worker 主要服务静态/缓存内容、后端服务全球分布(不存在单一最优位置)、Worker 与后端通信极少、或使用了 assets.run_worker_first = true(api.md)。

十、正向收益的度量参考

当 Smart Placement 真正适用(后端地理集中、数据库/API 调用密集)时,api.md 给出的参考改善幅度为:

  • 数据库密集型 Worker:请求耗时降低约 20~50%;
  • 多次后端 API 调用的 Worker:降低约 30~60%;
  • 后端地理越集中,改善越明显。

(以上为参考参考文档给出的典型改善区间,实际收益需以自身 Metrics 直方图对比为准。)

推荐的验证工作流:启用 → wrangler deploy → 等待 15 分钟 → 查询 placement_status 为 SUCCESS → 用 wrangler tail your-worker-name --header cf-placement 观测路由决策 → 对比 Metrics 中带/不带优化的请求耗时直方图 → 依据 第七节 的判定表决定保持或禁用。若需要更完整的配置与模式示例,可继续阅读本仓库的 smart-placement/configuration.md 与 smart-placement/patterns.md。

登录后查看全文
skills