Cloudflare Workers Smart Placement 排坑指南:从常见错误到架构拆分实战
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 章节。
补充替代方案(按优先级排序):
- 首选:拆分为独立 Worker(前端在边缘 + 后端开 Smart Placement);
- 显式关闭:
"mode": "off"; - 改用
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 的完整闭环是:
- 确认 Worker 有 fetch 处理器且有多次后端调用;
- 确认后端地理集中、且该 Worker 不承载静态资产;
- 在 wrangler.jsonc 中写入
{ "placement": { "mode": "smart" } }并wrangler deploy; - 等待最长 15 分钟分析期;
- 用 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。