Bindings 常见陷阱

# 绑定陷阱与故障排除 ## 关键：全局作用域变异 ### ❌ 头号陷阱：在全局作用域缓存 env typescript // ❌ 危险 - env 在部署时被缓存 const apiKey = env.API_KEY; // 错误：env 在全局作用域不可用 export default { async fetch(request: Request, env: Env) { // 使用了未定义或过期的值！ } } **为什么会出错：** - `env` 在全局作用域不可用 - 如果使用变通方法，Secrets 可能在不重新部署的情况下无法更新 - 导致 "Cannot read property 'X' of undefined" 错误 **✅ 始终在每个请求中访问 env：** typescript export default { async fetch(request: Request, env: Env) { const apiKey = env.API_KEY; // 每个请求都是最新的 } } ## 常见错误 ### "env.MY_KV is undefined" **原因：** 名称不匹配或未配置 **解决方案：** 检查 wrangler.jsonc（区分大小写），运行 `npx wrangler types`，验证 `npx wrangler kv namespace list` ### "Property 'MY_KV' does not exist on type 'Env'" **原因：** 类型未生成 **解决方案：** `npx wrangler types` ### "preview_id is required for --remote" **原因：** 缺少预览绑定 **解决方案：** 添加 `"preview_id": "dev-id"` 或使用 `npx wrangler dev` (本地模式) ### "Secret updated but Worker still uses old value" **原因：** 在全局作用域缓存或未重新部署 **解决方案：** 避免全局缓存，在更改 Secret 后重新部署 ### "KV get() returns null for existing key" **原因：** 最终一致性 (60秒)，命名空间错误，环境错误 **解决方案：** bash # 检查键是否存在 npx wrangler kv key get --binding=MY_KV "your-key" # 验证命名空间 ID npx wrangler kv namespace list # 检查环境 npx wrangler deployments list ### "D1 database not found" **解决方案：** `npx wrangler d1 list`，验证 wrangler.jsonc 中的 ID ### "Service binding returns 'No such service'" **原因：** 目标 Worker 未部署，名称不匹配，环境不匹配 **解决方案：** bash # 列出已部署的 Workers npx wrangler deployments list --name=target-worker # 检查服务绑定配置 cat wrangler.jsonc | grep -A2 services # 先部署目标 Worker cd ../target-worker && npx wrangler deploy ### "Rate limit exceeded" on KV writes **原因：** 每个键每秒写入 >1 次 **解决方案：** 使用不同的键、Durable Objects 或 Queues ## 类型安全陷阱 ### 缺少 @cloudflare/workers-types **错误：** `Cannot find name 'Request'` **解决方案：** `npm install -D @cloudflare/workers-types`，添加到 tscon