workers-best-practices

你对 Cloudflare Workers API、类型和配置的了解可能已过时。对于任何 Workers 代码任务（编写或审查），优先检索而非依赖预训练知识。

检索来源

在编写或审查 Workers 代码之前，获取最新版本。不要依赖内置知识来获取 API 签名、配置字段或绑定形状。

来源	如何检索	用途
Workers 最佳实践	获取 https://developers.cloudflare.com/workers/best-practices/workers-best-practices/	规范规则、模式、反模式
Workers 类型	参见 references/review.md 了解检索步骤	API 签名、处理程序类型、绑定类型
Wrangler 配置模式	node_modules/wrangler/config-schema.json	配置字段、绑定形状、允许值
Cloudflare 文档	搜索工具或 https://developers.cloudflare.com/workers/	API 参考、兼容性日期/标志

首先：获取最新参考

在审查或编写 Workers 代码之前，检索当前的最佳实践页面和相关类型定义。如果项目的 node_modules 中有旧版本，优先使用最新发布版本。

# 获取最新的 workers 类型
mkdir -p /tmp/workers-types-latest && \
  npm pack @cloudflare/workers-types --pack-destination /tmp/workers-types-latest && \
  tar -xzf /tmp/workers-types-latest/cloudflare-workers-types-*.tgz -C /tmp/workers-types-latest
# 类型文件位于 /tmp/workers-types-latest/package/index.d.ts

参考文档

• references/rules.md — 所有最佳实践规则，包含代码示例和反模式
• references/review.md — 类型验证、配置验证、绑定访问模式、审查流程

规则快速参考

配置

规则	摘要
兼容性日期	新项目将 compatibility_date 设置为当天；现有项目定期更新
nodejs_compat	启用 nodejs_compat 标志——许多库依赖 Node.js 内置模块
wrangler types	运行 wrangler types 生成 Env——永远不要手写绑定接口
密钥	使用 wrangler secret put，切勿在配置或源代码中硬编码密钥
wrangler.jsonc	对非密钥设置使用 JSONC 配置——新功能仅支持 JSON

请求与响应处理

规则	摘要
流处理	对大型/未知负载使用流——切勿对无界数据使用 await response.text()
waitUntil	使用 ctx.waitUntil() 处理响应后工作；不要解构 ctx

架构

规则	摘要
绑定优于 REST	使用进程内绑定（KV、R2、D1、Queues）——而非 Cloudflare REST API
Queues 与 Workflows	将异步/后台工作移出关键路径
服务绑定	使用服务绑定进行 Worker 间调用——而非公共 HTTP
Hyperdrive	始终使用 Hyperdrive 连接外部 PostgreSQL/MySQL

可观测性

规则	摘要
日志与追踪	在配置中启用 observability 并设置 head_sampling_rate；使用结构化 JSON 日志

代码模式

规则	摘要
无全局请求状态	切勿将请求作用域的数据存储在模块级变量中
未处理的 Promise	每个 Promise 必须被 await、return、void 或传递给 ctx.waitUntil()

安全

规则	摘要
Web Crypto	使用 crypto.randomUUID() / crypto.getRandomValues()——切勿使用 Math.random() 处理安全相关
不使用 passThroughOnException	使用显式的 try/catch 并返回结构化错误响应

需要标记的反模式

反模式	为何重要
对无界数据使用 await response.text()	内存耗尽——128 MB 限制
在源代码或配置中硬编码密钥	通过版本控制泄露凭据
使用 Math.random() 生成令牌/ID	可预测，非加密安全
裸 fetch() 不带 await 或 waitUntil	未处理的 Promise——结果丢失，错误被吞没
使用模块级可变变量存储请求状态	跨请求数据泄露、状态过期、I/O 错误
在 Worker 内部调用 Cloudflare REST API	不必要的网络跳转、认证开销、增加延迟
使用 ctx.passThroughOnException() 处理错误	隐藏错误，使调试不可能
手写 Env 接口	与实际 wrangler 配置绑定不一致
直接字符串比较密钥值	时序侧信道——应使用 crypto.subtle.timingSafeEqual
解构 ctx（const { waitUntil } = ctx）	丢失 this 绑定——运行时抛出“非法调用”
在 Env 或处理程序参数上使用 any	破坏所有绑定访问的类型安全
使用 as unknown as T 双重类型转换	隐藏真实的类型不兼容——应修复设计
在平台基类上使用 implements（而非 extends）	遗留用法——丢失 this.ctx、this.env。适用于 DurableObject、WorkerEntrypoint、Workflow
在平台基类内部使用 env.X	在继承 DurableObject、WorkerEntrypoint 等的类中应使用 this.env.X

审查流程

1. 检索 — 获取最新的最佳实践页面、workers 类型和 wrangler 模式
2. 阅读完整文件 — 不仅仅是差异；上下文对绑定访问模式很重要
3. 检查类型 — 绑定访问、处理程序签名、无 any、无不安全类型转换（参见 references/review.md）
4. 检查配置 — compatibility_date、nodejs_compat、observability、密钥、绑定与代码一致性
5. 检查模式 — 流处理、未处理的 Promise、全局状态、序列化边界
6. 检查安全 — 加密使用、密钥处理、时序安全比较、错误处理
7. 使用工具验证 — npx tsc --noEmit，使用 lint 检查 no-floating-promises
8. 参考规则 — 参见 references/rules.md 了解每个规则的正确模式

范围

本技能涵盖 Workers 特定的最佳实践和代码审查。相关主题：

• Durable Objects：加载 durable-objects 技能
• Workflows：参见 Workflows 规则
• Wrangler CLI 命令：加载 wrangler 技能

原则

• 确保准确。 在标记之前先检索。如果对某个 API、配置字段或模式不确定，先查阅文档。
• 提供证据。 引用行号、工具输出或文档链接。
• 关注开发者会复制的内容。 示例和文档中的 Workers 代码会被粘贴到生产环境中。
• 正确性优先于完整性。 一个简洁且能工作的示例胜过包含错误但全面的示例。