Cloudflare Workers Smart Placement 排错完全指南:常见错误、性能陷阱与架构避坑(cloudflare-deploy 技能实战)
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 组织的四份参考文档,它们共同构成了完整的知识闭环:
- smart-placement/README.md:核心概念、决策树、"何时启用/不启用"清单;
- smart-placement/configuration.md:
wrangler.jsonc配置、mode取值、校验规则、Pages 警告; - smart-placement/patterns.md:前后端拆分、数据库 Worker、SSR/API 网关、Durable Objects 聚合等实战模式;
- smart-placement/api.md:Placement Status API、
cf-placement头、请求耗时指标与监控命令; - 本篇要讲解的 smart-placement/gotchas.md:常见错误与性能陷阱的集中排错手册。
在 SKILL.md 的决策树中,Smart Placement 被定位为"优化到后端基础设施的延迟(而非面向用户的延迟)",这一定位正是后续所有 gotcha 的根源:Smart Placement 的目标是降低后端通信延迟,任何与这一目标相悖的场景都会产生问题。
一、常见错误:四个高频报错/现象的排查
1. INSUFFICIENT_INVOCATIONS
原因:流量不足,Smart Placement 无法积累足够样本来分析并做出放置决策。
解决方案(来自 gotchas.md 原文,全部保留):
- 确保 Worker 能收到持续、稳定的全球流量;
- 等待更长时间——分析最长需要 15 分钟;
- 从多个全球地理位置发送测试流量(单一地域的流量无法代表全球拓扑);
- 检查 Worker 是否具备
fetch事件处理器(没有fetchhandler 的 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 给出了按优先级排列的三种解决方案:
- (推荐)拆分为独立 Worker:前端留在边缘,后端启用 Smart Placement;
- 将
"mode"显式设为"off"以禁用 Smart Placement; - 设置
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); - 没有
fetchhandler 的 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 的
fetchhandler 运行在哪里"——当协调 Worker 需要向多个 DO 发起调用时,把它放在靠近 DO 区域的位置才有意义(详见 patterns.md 的 Durable Objects 章节)。
七、启用要求与硬性限制
启用要求
- Wrangler 2.20.0+(必需);
- 持续的多地域流量(单一地域流量不足以支撑分析);
- 只影响
fetchhandler——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 方法而非
fetchhandler 的 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。