← 中文资源

简体中文版本

Cloudflare Wrangler Worker 中绑定未找到

Cloudflare Worker 抛出"binding X does not exist",因为代码中的 KV、R2 或 D1 绑定未在 wrangler.toml 或仪表板中声明。

阅读英文原文

症状分析

Cloudflare Worker 抛出“binding X does not exist”,因为代码中的 KV、R2 或 D1 绑定未在 wrangler.toml 或仪表板中声明。 该错误在生产环境中出现,但可能不会在本地开发中复现,因为触发条件依赖于部署环境或运行时配置。理解完整的症状集合有助于将此问题与类似错误区分开来。

诊断实践

按照前置事项中的诊断步骤定位原因。每个步骤包含命令和输出解读。目标是缩小问题范围:配置、运行时还是应用代码。在最小化环境中复现错误后再应用修复。

根因

The binding is not declared in the environment configuration, so the Workers runtime does not inject it into the global scope, causing the reference to be undefined.

修复

Add the binding to wrangler.toml with the correct name and ID, deploy with wrangler deploy, and ensure the binding name in code matches the configuration exactly. 应用修复后,监控系统以确认错误在负载下或不同环境中不再复现。

验证

Deploy the Worker and test the endpoint that uses the binding; confirm the KV or R2 operation succeeds. 如果验证通过,修复即确认;如果未通过,重新检查诊断步骤中是否遗漏了促成因素。

诊断命令

运行以下命令复现和诊断问题:

cat wrangler.toml | grep -A5 kv_namespaces
npx wrangler deploy --dry-run