workers-best-practices

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

以项目已安装的版本、生成的类型和 Wrangler 兼容性设置作为现有代码的基准。检索相关 Cloudflare 文档，以核实 API、配置、运行时行为和限制相关声明。

参考资料

阅读与任务相关的部分：

参考资料	使用时机
配置与可观测性	兼容性日期、绑定、生成的类型、密钥、日志和追踪
运行时模式	流式处理、Promise 生命周期、请求状态、服务调用、安全性和运行时测试
平台 API 检查	处理程序签名、平台类、绑定访问和序列化

如缺少依据，请查阅 Workers 最佳实践，或在 Cloudflare 文档目录中查找相关产品。配置字段请使用已安装的 Wrangler schema。更新的类型包不能取代项目配置的目标版本。

保持兼容性日期为最新

创建新的 Workers 时使用今天的日期。建议定期更新现有 Workers，并审查兼容性变更、运行相关测试。根据已配置的日期和标志评估现有行为；请参阅兼容性指南。

启用可观测性

创建 Worker 或为生产环境准备 Worker 时，请启用 Workers Logs 和 Traces。将 observability.enabled 和 observability.traces.enabled 设为 true；仅设置顶层选项并不会启用追踪。使用结构化 JSON 日志，并根据工作负载配置采样。审查时，指出缺少日志或追踪的情况。请参阅配置示例。

需要指出的反模式

反模式	后果及建议模式
对无界数据调用 await response.text() 或类似的缓冲操作	可能耗尽 Worker 内存；对大型或无界的请求和响应正文进行流式处理。
在源代码或配置中硬编码密钥	会通过版本控制泄露凭据；请使用 Wrangler secrets。
使用 Math.random() 生成安全敏感的令牌或 ID	值可预测；请使用 crypto.randomUUID() 或 crypto.getRandomValues()。
启动异步工作后既不等待、不返回，也不将其关联到 ctx.waitUntil()	工作可能被丢弃，错误也可能被忽略；请将其关联到请求或后台工作的生命周期。
模块级可变请求状态	会导致数据在请求之间泄露，并可能引发 I/O 所有权错误；请显式传递请求状态。
对可通过 Worker 绑定执行的操作调用 Cloudflare REST API	会增加网络和身份验证开销；请使用可用的绑定。
将 ctx.passThroughOnException() 用作通用错误处理	可能通过将请求转发到源站来掩盖 Worker 故障；请使用显式错误处理和结构化错误响应。
手写与 Wrangler 绑定重复的 Env	可能与配置不一致；请使用 wrangler types 生成绑定类型。
直接比较机密值字符串	可能泄露时序差异；请使用 Web Crypto 比较模式。
解构 ctx 方法，例如 const { waitUntil } = ctx	会丢失接收者；请调用 ctx.waitUntil(...)。
在 Env 或处理程序参数上使用 any	会隐藏绑定和处理程序契约错误；请使用项目生成的类型和平台类型。
使用 as unknown as T 强制匹配平台类型	会隐藏不兼容问题；请修复底层契约。
使用 implements 代替继承平台基类	不会继承运行时行为、this.ctx 或 this.env；请使用相应的基类。
在平台类方法中使用未绑定的 env.X	应通过 this.env.X 访问绑定；请参阅绑定访问模式。
对 Queues、Workflow 步骤、存储和 WebSockets 一概使用同一序列化规则	可能拒绝有效负载，或接受不受支持的有效负载；请查看具体 API 和编码方式。

验证

针对受影响的 Workers 行为，使用项目现有的检查：对类型检查相关绑定或处理程序契约的变更，并对行为变更运行相关运行时测试。保留仓库要求的检查；范围有限的编辑无需进行全面的 Workers 审查。

范围

此技能涵盖 Workers 专属的最佳实践和代码审查。相关主题：

• Durable Objects：加载 durable-objects 技能
• Workflows：参阅 Workflows 规则
• CLI 命令：加载 cf-cli 技能，或在包含 Wrangler 配置文件的项目中加载 wrangler 技能