Secrets Store 常见陷阱

# 常见问题与避坑指南 ## 常见错误 ### ".get() 在出错时抛出异常" **原因:** 假设 `.get()` 在失败时返回 null 而不是抛出异常 **解决方案:** 始终将 `.get()` 调用包裹在 try/catch 块中以优雅地处理错误 typescript try { const key = await env.API_KEY.get(); } catch (error) { return new Response("配置错误", { status: 500 }); } ### "记录密钥值" **原因:** 在控制台或错误消息中意外记录了密钥值 **解决方案:** 仅记录元数据（例如 "已获取 API_KEY"），切勿记录实际的密钥值 ### "模块级密钥访问" **原因:** 在模块初始化期间（env 可用之前）尝试访问密钥 **解决方案:** 仅在请求作用域内缓存密钥，不要在模块级别缓存 ### "存储中找不到密钥" **原因:** 密钥名称不存在、大小写不匹配、缺少 workers 作用域或 store_id 不正确 **解决方案:** 使用 `wrangler secrets-store secret list --remote` 验证密钥是否存在，检查名称是否完全匹配（区分大小写），确保密钥具有 `workers` 作用域，并验证 store_id 是否正确 ### "作用域不匹配" **原因:** 密钥存在但缺少 `workers` 作用域（仅具有 `ai-gateway` 作用域） **解决方案:** 更新密钥作用域：`wrangler secrets-store secret update --name SECRET --scopes workers --remote` 或通过仪表板添加 ### "JSON 解析失败" **原因:** 在密钥中存储了无效的 JSON，导致运行时解析失败 **解决方案:** 存储前验证 JSON： bash # 存储前验证 echo '{"key":"value"}' | jq . && echo '{"key":"value"}' | wrangler secrets-store secret create --name CONFIG --scopes workers --remote 运行时解析并处理错误： typescript try { const configStr = await env.CONFIG.get(); const config = JSON.parse(configStr); } catch (error) { console.error("无效的配置 JSON:", error); return new Response("无效的配置", { status: 500 }); } ### "无法在本地开发中访问密钥" **原因:** 尝试在本地开发环境中访问生产环境密钥 **解决方案:** 为开发创建仅本地使用的密钥（不带 `--remote` 标志）：`wrangler secrets-store secret create --name API_KEY --scopes workers` ### "属性 'get' 不存在" **原因:** 缺少密钥绑定的 TypeScript 类型定义 **解决方案:** 定义带有 get 方法的接口：`interface Env { API_KEY: { get(): Promise }; }` ###