Cloudflare Workers Smart Placement 排坑指南:从常见错误到架构拆分实战

原创2026-10-11 21:40:372,246 阅读

Cloudflare Workers Smart Placement 排坑指南:从常见错误到架构拆分实战

导读

Smart Placement 是 Cloudflare Workers 的一项自动工作负载放置优化能力:它不再默认把请求路由到离用户最近的边缘节点,而是基于请求耗时数据,把 Worker 智能调度到离后端基础设施(数据库、内部 API)更近的数据中心,从而降低整体请求延迟。本指南以 autoskills 仓库中 smart-placement/gotchas.md 为核心,系统梳理启用 Smart Placement 后最常见的错误、性能劣化场景与架构误用,并给出可直接复制的修复配置与代码,帮助你判断"该不该开、开了怎么调、出问题怎么救"。


一、先理解:Smart Placement 到底优化什么

在进入排坑之前,先明确 Smart Placement 的边界,否则后面 90% 的坑都会踩得莫名其妙。

根据 smart-placement/README.md 的定义:Smart Placement 会分析 Worker 在 Cloudflare 全球网络上的请求耗时,将请求转发到"离后端更近"而非"离用户更近"的数据中心。它只在后端往返(round trip)占据请求耗时主导时才有价值——例如 Worker 需要多次访问地理上集中的数据库或内部服务。

仓库根目录的 SKILL.md 在决策索引中把它定位为"优化到后端基础设施(而非用户)的延迟"的场景,与 Argo Smart Routing(优化路由)并列但用途不同:

Need to run code?
└─ Optimize latency to backend infrastructure → smart-placement/

对应到 smart-placement/README.md 的决策树,判断标准非常直接:

Does your Worker have a fetch handler?
├─ No → Smart Placement won't work (skip)
└─ Yes
   │
   Does it make multiple backend calls (DB/API)?
   ├─ No → Don't enable (won't help)
   └─ Yes
      │
      Is backend geographically concentrated?
      ├─ No (globally distributed) → Probably won't help
      └─ Yes or uncertain
         │
         Does it serve static assets with run_worker_first=true?
         ├─ Yes → Don't enable (will hurt performance)
         └─ No → Enable Smart Placement
            │
            After 15min, check placement_status
            ├─ SUCCESS → Monitor metrics
            ├─ INSUFFICIENT_INVOCATIONS → Need more traffic
            └─ UNSUPPORTED_APPLICATION → Disable (hurting performance)

一句话总结适用前提:只有"带 fetch 处理器的 Worker + 多次后端调用 + 后端地理集中"三者同时满足,Smart Placement 才有正面收益。下面所有坑,几乎都是这三条前提被破坏导致的。


二、四大常见错误:错误码、原因与解决方案

2.1 INSUFFICIENT_INVOCATIONS(调用量不足)

原因:Smart Placement 需要足够的请求量来做放置决策分析,当前流量不足。

解决方案(按顺序执行):

  • 确保 Worker 能接收到一致的全球流量(consistent global traffic),而不是偶发的零星请求;
  • 等待更长时间——分析最长需要 15 分钟,不要刚部署 2 分钟就判定失败;
  • 从多个全球地理位置发送测试流量,单一地域的流量无法形成有效对比样本;
  • 检查 Worker 是否存在 fetch 事件处理器——没有 fetch handler 的 Worker 根本不会被分析。

2.2 UNSUPPORTED_APPLICATION(应用不受支持/被判定劣化)

原因:这是 Smart Placement 给出的最直白的"负面评价"——分析结果表明放置优化反而让 Worker 变慢了,于是平台自动回退。常见诱因包括:

  • Worker 不发起后端调用(纯边缘逻辑,在边缘跑反而更快);
  • 后端调用已被缓存(此时用户到边缘的网络延迟比后端延迟更重要);
  • 后端服务本身全球分布良好(不存在"单一最优位置");
  • Worker 只服务静态资源或 Pages 内容(静态资源永远应该从离用户最近的边缘返回)。

解决方案:

  • 直接关闭 Smart Placement:{ "placement": { "mode": "off" } };
  • 重新评估该 Worker 是否真的能从 Smart Placement 获益;
  • 考虑引入缓存策略减少后端调用次数;
  • 对 Pages/Assets 类 Worker,应拆出独立的后端 Worker 来承载 Smart Placement,前端 Worker 保持边缘运行。

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

原因:可能是以下几种情况之一——Smart Placement 未启用、启用后分析时间不足、流量不足、或分析尚未完成。

解决方案:

  • 确认配置文件中已启用 Smart Placement(见下文配置节);
  • 部署后等待 15 分钟以上再查看指标;
  • 验证 Worker 流量是否足够;
  • 通过 API 检查 placement_status 是否为 SUCCESS(查询方法见第四节)。

2.4 "cf-placement header missing"(缺少 cf-placement 响应头)

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

解决方案:确认 Smart Placement 已启用;等待分析完成(约 15 分钟);检查该 beta 功能在当前账号/时间点是否仍可用。注意:cf-placement 是 beta 特性,存在 GA 前被移除的可能,详见 smart-placement/api.md。


三、两个最致命的结构性误配置

3.1 Pages/Assets + Smart Placement:静态资源加载变慢 2~5 倍

问题现象:在 run_worker_first = true 的情况下启用 Smart Placement,静态资源(HTML、CSS、JS、图片)加载速度下降 2~5 倍。

根因:Smart Placement 会把所有请求(包括静态资源请求)路由到远端数据中心;而静态内容必须始终从离用户最近的边缘节点返回。仓库 static-assets/gotchas.md 也印证了这一点:run_worker_first=true + Smart Placement 会把所有请求都穿过单一 smart-placed 位置,从而抬高延迟。

错误配置示例:

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

正确做法:拆分为两个 Worker——前端 Worker 留在边缘,后端 API Worker 开启 Smart Placement:

// ✅ GOOD - Assets 在边缘,API 被优化
// frontend/wrangler.jsonc
{
  "name": "frontend",
  "assets": { "run_worker_first": true }
  // 不写 placement 字段 - 保持在边缘
}

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

这是最常见且影响最大的 Smart Placement 误配置之一。完整的前后端拆分配置还可以参考 smart-placement/configuration.md 中的 Frontend + Backend Split 章节。

补充替代方案(按优先级排序):

  1. 首选:拆分为独立 Worker(前端在边缘 + 后端开 Smart Placement);
  2. 显式关闭:"mode": "off";
  3. 改用 assets.run_worker_first = false,让静态内容直接由边缘资产服务返回,绕过 Worker。

另外注意,static-assets/configuration.md 还提供了数组式路由匹配的折中方案:"run_worker_first": ["/api/*", "!/api/docs/*"]——只让 /api/* 等少量路由触发 Worker,静态资源默认走边缘,同样能规避此问题。

3.2 Monolithic Full-Stack Worker:前后端逻辑塞进一个 Worker

问题现象:把前端渲染与后端数据逻辑放在同一个 Worker 中并启用 Smart Placement。

根因:Smart Placement 优化的是后端延迟,但代价是牺牲用户侧响应时间——整个 Worker(包括负责响应用户的部分)被调度到了后端附近,而不是用户附近。

解决方案:拆成两个 Worker,前端显式保持边缘运行,后端开启 Smart Placement 并通过 Service Binding 联通:

// 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" }]
}

这里的 services Service Binding 配置方式与仓库 bindings/configuration.md 中 Compute Bindings 的写法一致(可选 environment 字段指定目标环境),前端代码中通过 env.BACKEND.fetch(request) 转发请求即可。推荐的架构形态如下:

User → Frontend Worker (at edge, close to user)
         ↓ Service Binding
       Backend Worker (Smart Placement enabled, close to DB/API)
         ↓
       Database/Backend Service

四、本地开发与验证:为什么 wrangler dev 里"没效果"

常见困惑:本地 wrangler dev 跑起来后,Smart Placement 完全没有生效迹象。

解释:这是正常行为。Smart Placement 只在生产部署中激活,本地开发环境(wrangler dev / Miniflare)不参与全球网络的流量分析,自然也不会生效。

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

wrangler deploy --env staging

部署后配合监控命令验证(详见 smart-placement/api.md):

# 部署
wrangler deploy

# 查询 placement_status
curl -H "Authorization: Bearer $TOKEN" \
  https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/services/$WORKER_NAME \
  | jq .result.placement_status

# 跟踪日志中的 cf-placement 头
wrangler tail your-worker-name --header cf-placement

五、基线流量与分析时间:这些"异常"其实正常

启用 Smart Placement 后有两个容易引起误判的正常现象:

  • 1% 基线流量:Smart Placement 会自动把 1% 的请求不做优化地路由,用于与优化后的流量进行性能对比。因此你会看到少量请求的耗时明显偏高、且不带远程路由特征——这是设计如此,不是故障。
  • 最长 15 分钟分析期:分析期间 Worker 运行在边缘(即默认位置),placement_status 尚未变为 SUCCESS。在此期间不要急着下"没效果"的结论,应持续监控状态字段。

状态机速查(来自 smart-placement/api.md):

状态 含义 处置
undefined 尚未分析 等待,继续观察
SUCCESS 分析完成,优化已生效 进入指标监控
INSUFFICIENT_INVOCATIONS 流量不足 增加多地域流量
UNSUPPORTED_APPLICATION 优化反而变慢,已回退 关闭或重构(<1% 的 Worker 会出现)

六、RPC 方法的致命限制:Smart Placement 对 RPC 无效

问题现象:后端 Worker 已开启 Smart Placement,但通过 Service Binding 的 RPC 调用依然很慢。

根因(关键架构约束):Smart Placement 只作用于 fetch 处理器。RPC 方法(WorkerEntrypoint 派生的 Service Binding)永远不会被 Smart Placement 影响——因为 RPC 调用绕过了 fetch 处理器,而 Smart Placement 只能路由 fetch 请求。同理,命名入口(named entrypoints)、队列消费者、scheduled 定时处理器等事件类型也不受影响,这一点在 smart-placement/configuration.md 中有明确列表。

修复方案:把 RPC 改成 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);
  }
}

如果业务上必须保留 RPC 接口,另一个思路是加一个带 fetch 处理器的 wrapper Worker 转发到后端 RPC(代价是增加一次额外跳转延迟)。结论是:想让 Smart Placement 生效,后端入口必须是 fetch 处理器。


七、硬性要求与限制速查表

资源/限制 数值 说明
分析时间 最长 15 分钟 启用后开始计时
基线流量 1% 不做优化地路由,用于对比
最低 Wrangler 版本 2.20.0+ 低于此版本不支持
流量要求 多地域且持续 单一地域流量不足以分析
影响范围 仅 fetch 处理器 RPC 方法与命名入口不受影响

其他值得注意的边界:

  • 与显式放置(Explicit Placement,region/host/hostname 字段)互斥,mode 不能与这些字段同时出现,详见 smart-placement/configuration.md 的 Validation Rules;
  • 对 KV、R2 或外部 API 的访问延迟没有帮助——wrangler/gotchas.md 明确指出,Smart Placement 主要对 D1 / Durable Objects 这类后端存储的访问有意义;
  • 所有 Workers 套餐(Free、Paid、Enterprise)均可用。

八、如何关闭 Smart Placement

两种关闭方式行为完全一致:

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

两种方式下,Worker 都运行在离用户最近的边缘位置。


九、什么时候坚决不要开 Smart Placement

以下场景不会获益,甚至可能更差,应保持关闭:

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

指标自检方法:在 Dashboard 的 Request Duration 指标中对比"开启优化(99% 流量)"与"基线(1% 流量)"两组耗时分布。若 WITH ≈ WITHOUT,收益中性,可考虑关闭以释放资源;若 WITH > WITHOUT,说明优化在帮倒忙,应立即用 mode: "off" 关闭。典型收益出现在数据库密集型 Worker(请求耗时降低 20%~50%)和多次后端 API 调用的 Worker(30%~60%),前提是后端地理集中、Worker 使用 fetch 处理器。


十、完整的决策与配置速览

最终,启用 Smart Placement 的完整闭环是:

  1. 确认 Worker 有 fetch 处理器且有多次后端调用;
  2. 确认后端地理集中、且该 Worker 不承载静态资产;
  3. 在 wrangler.jsonc 中写入 { "placement": { "mode": "smart" } } 并 wrangler deploy;
  4. 等待最长 15 分钟分析期;
  5. 用 API 查询 placement_status:SUCCESS → 监控指标;INSUFFICIENT_INVOCATIONS → 补充多地域流量;UNSUPPORTED_APPLICATION → 关闭或按上文拆分架构重构。

配套的完整实操示例(后端数据库 Worker、前端/后端 Service Binding 拆分、外部 API 集成、SSR/API 网关、Durable Objects 协调者模式)可继续阅读 smart-placement/patterns.md;监控与 API 细节见 smart-placement/api.md;基础配置与类型定义见 smart-placement/configuration.md。

登录后查看全文
autoskills