你对 Cloudflare Workers API、类型和配置的了解可能已过时。编写或审查 Workers 代码时，优先检索而非预训练。
将项目已安装的版本、生成的类型以及 Wrangler 兼容性设置作为现有代码的基线。检索相关 Cloudflare 文档，以验证 API、配置、运行时行为和限制方面的说法。
参考资料
阅读与任务相关的部分：
| 参考 | 何时使用 | |-----------|----------------| | [配置与可观测性](references/configuration.md) | 兼容性日期、绑定、生成的类型、秘密、日志和追踪 | | [运行时模式](references/runtime-patterns.md) | 流式处理、Promise 生命周期、请求状态、服务调用、安全性和运行时测试 | | [平台 API 检查](references/platform-apis.md) | 处理程序签名、平台类、绑定访问和序列化 |
如果缺少证据，请查阅 Workers 最佳实践 或在 Cloudflare 文档目录 中查找受影响的产品。对于配置字段，请使用已安装的 Wrangler schema。较新的类型包不会取代项目配置的目标。
保持兼容性日期最新
为新的 Workers 使用今天的日期。鼓励定期更新现有 Workers，审查兼容性变更并运行相关测试。根据已配置的日期和标志评估现有行为；参见 [兼容性指南](references/configuration.md#keep-compatibility_date-current)。
启用可观测性
在创建或准备用于生产的 Worker 时，启用 Workers Logs 和 Traces。将 observability.enabled 和 observability.traces.enabled 设置为 true；仅顶层设置不会启用 traces。使用结构化 JSON 日志记录，并针对工作负载配置采样。在审查期间，标记缺失的日志或 traces。参见 [配置示例](references/configuration.md#enable-workers-logs-and-traces)。
需要标记的反模式
| 反模式 | 后果与首选模式 | |-------------|-----------------------------------| | await response.text() 或对无界数据进行类似缓冲 | 可能耗尽 Worker 内存；[流式处理大型或无界主体](references/runtime-patterns.md#stream-request-and-response-bodies)。 | | 在源代码或配置中硬编码秘密 | 通过版本控制泄露凭据；使用 Wrangler secrets。 | | 使用 Math.random() 生成安全敏感令牌或 ID | 值可预测；使用 crypto.randomUUID() 或 crypto.getRandomValues()。 | | 启动异步工作但未等待、返回或将其附加到 ctx.waitUntil() | 工作可能被丢弃并错过错误；将其绑定到请求或后台工作生命周期。 | | 模块级可变请求状态 | 会在请求之间泄露数据，并可能导致 I/O 所有权错误；显式传递请求状态。 | | 对可通过 Worker 绑定执行的操作调用 Cloudflare REST API | 增加网络和身份验证开销；使用可用绑定。 | | 将 ctx.passThroughOnException() 用作通用错误处理 | 可能通过转发到源站来掩盖 Worker 故障；使用显式错误处理和结构化错误响应。 | | 手写 Env 重复 Wrangler 绑定 | 可能与配置漂移；使用 wrangler types 生成绑定类型。 | | 直接对秘密值进行字符串比较 | 可能暴露时序差异；使用 [Web Crypto 比较模式](references/runtime-patterns.md#use-web-crypto-for-secure-token-generation)。 | | 解构 ctx 方法，例如 const { waitUntil } = ctx | 会丢失接收者；调用 ctx.waitUntil(...)。 | | 在 Env 或处理程序参数上使用 any | 会隐藏绑定和处理程序契约错误；使用项目生成的类型和平台类型。 | | 使用 as unknown as T 强制匹配平台类型 | 会隐藏不兼容问题；修复底层契约。 | | 使用 implements 代替扩展平台基类 | 不会继承运行时行为、this.ctx 或 this.env；使用适当的基类。 | | 在平台类方法中使用未绑定的 env.X | 绑定可通过 this.env.X 使用；参见 [绑定访问模式](references/platform-apis.md#binding-access--the-most-common-error)。 | | 在 Queues、Workflow steps、存储和 WebSockets 之间应用同一序列化规则 | 可能拒绝有效负载或接受不支持的负载；检查 [特定 API 与编码](references/platform-apis.md#serialization-boundaries)。 |
验证
对受影响的 Workers 行为使用项目现有检查：对绑定或处理程序契约变更进行类型检查，并为行为变更运行相关运行时测试。保留必需的仓库检查；窄范围编辑不需要完整的 Workers 审计。
范围
此 skill 涵盖 Workers 特定最佳实践和代码审查。对于相关主题：
- Durable Objects：加载
durable-objectsskill - Workflows：参见 Workflows 规则
- Wrangler CLI 命令：加载
wranglerskill