编写或审查 Cloudflare Workers 代码时…

在编写、审查或配置 Cloudflare Workers 生产应用时，以项目已安装版本与官方文档为准，并检查兼容性日期、可观测性和一系列常见反模式。

适用场景

解决思路

1. 优先检索而非依赖预训练知识：Cloudflare Workers 的 API、类型和配置知识可能已过时，写或审查 Workers 代码时应主动检索文档。
2. 以项目已安装的版本、生成的类型和 Wrangler compatibility 设置作为现有代码的基线。
3. 检索相关 Cloudflare 文档，核实 API、配置、运行时行为和限制类声明。
4. 按任务读取对应 reference 章节：references/configuration.md 用于 compatibility dates、bindings、generated types、secrets、logs、traces；references/runtime-patterns.md 用于 streaming、promise lifetime、request state、service calls、security、runtime tests；references/platform-apis.md 用于 handler 签名、平台类、binding 访问和序列化。
5. 缺少证据时，查阅 Workers best practices 文档（https://developers.cloudflare.com/workers/best-practices/workers-best-practices/）或在 Cloudflare docs directory（https://developers.cloudflare.com/directory/）查找相关产品；配置字段以已安装的 Wrangler schema 为准；更新的 type package 不能取代项目已配置的 target。
6. 保持 compatibility_date 最新：新建 Worker 使用当天日期；对已有 Worker 鼓励定期更新，审查兼容性变更并运行相关测试；按已配置的日期和 flags 评估现有行为。
7. 创建或准备上线 Worker 时启用 Workers Logs 和 Traces，将 observability.enabled 与 observability.traces.enabled 都设为 true（只设顶层配置不会启用 traces）；使用结构化 JSON 日志并按工作负载配置采样；审查时标记缺失的 logs 或 traces。
8. 反模式：对无界数据执行 `await response.text()` 之类的缓冲操作会耗尽 Worker 内存，应改为流式处理大体积或无界响应体。
9. 反模式：在源码或配置中硬编码 secrets 会通过版本控制泄露凭证，应使用 Wrangler secrets。
10. 反模式：用 `Math.random()` 生成安全敏感 token 或 ID 会产生可预测值，应使用 `crypto.randomUUID()` 或 `crypto.getRandomValues()`。
11. 反模式：启动异步工作却不 await、不 return、也不挂到 `ctx.waitUntil()` 上，工作可能被丢弃且错误被忽略；应把它绑定到请求或后台工作生命周期。
12. 反模式：模块级可变请求状态会跨请求泄露数据并引发 I/O 归属错误；应显式传递请求状态。
13. 反模式：对 Worker bindings 已能完成的操作去调用 Cloudflare REST API，会带来额外的网络与认证开销；应使用可用的 binding。
14. 反模式：把 `ctx.passThroughOnException()` 当通用错误处理会掩盖 Worker 故障（转发到源站）；应使用显式错误处理和结构化错误响应。
15. 反模式：手写 `Env` 重复 Wrangler bindings 会与配置漂移；应使用 `wrangler types` 生成 binding 类型。
16. 反模式：直接字符串比较 secret 值会暴露时序差异；应使用 Web Crypto 比较模式。
17. 反模式：解构 `ctx` 方法（如 `const { waitUntil } = ctx`）会丢失接收者；应调用 `ctx.waitUntil(...)`。
18. 反模式：在 `Env` 或 handler 参数上使用 `any` 会掩盖 binding 与 handler 契约错误；应使用项目生成的类型和平台类型。
19. 反模式：用 `as unknown as T` 强行匹配平台类型会掩盖不兼容；应修复底层契约。
20. 反模式：用 `implements` 代替继承平台基类不会继承运行时行为、`this.ctx` 或 `this.env`；应使用合适的基类。
21. 反模式：在平台类方法中使用未绑定的 `env.X`；bindings 应通过 `this.env.X` 访问。
22. 反模式：把同一套序列化规则套用到 Queues、Workflow steps、存储和 WebSockets 上，可能拒绝合法 payload 或接受不支持的 payload；应检查具体 API 与编码。
23. 验证：使用项目现有的检查覆盖受影响的 Workers 行为——对 binding 或 handler 契约变更做类型检查，对行为变更运行相关运行时测试；保留仓库必需的检查。
24. 范围限定：本技能只覆盖 Workers 专属最佳实践与代码审查；Durable Objects 加载 `durable-objects` 技能，Workflows 参考 Rules of Workflows 文档，Wrangler CLI 命令加载 `wrangler` 技能。

适用边界 · 注意事项

• 项目不使用 Cloudflare Workers / Wrangler 时，这些绑定、兼容性日期和运行时限制的规则不适用。
• 窄范围的小改动不需要做完整的 Workers 审计，只需运行受影响的现有检查。
• Durable Objects、Workflows 或纯 Wrangler CLI 命令相关的问题应转用对应的专门技能或文档。