Cloudflare Workers + KV Mock API 部署踩坑总结

1. 环境变量 DB_JSON 超过 5.1KB 限制

  • 问题：直接用 wrangler secret put DB_JSON < db.json 注入大文件时报错：Text binding ‘DB_JSON’ is too large。
  • 解决：改用 Cloudflare KV 存储大数据，Worker 运行时从 KV 读取。

2. wrangler.toml 配置格式错误

  • 问题：[[kv_namespaces]] 下写了 name、type、account_id 等字段，导致 warning。
  • 解决：[[kv_namespaces]] 下只保留 binding 和 id，其他字段放到文件顶层。

3. 写入 KV 时命令格式错误

  • 问题：用 wrangler kv:key put 或 wrangler kv:namespace create 等老版本命令，或参数顺序、语法不对。
  • 解决：新版 wrangler 用空格分隔，如：
    • 创建命名空间：wrangler kv namespace create DB
    • 写入数据：wrangler kv key put --binding=DB DB_JSON "$(Get-Content -Raw db.json)" --remote

4. Windows 下 PowerShell 与 cmd 语法差异

  • 问题：cmd 下 $(Get-Content -Raw db.json) 不会被替换，写入 KV 的是字符串而不是内容。
  • 解决：用 PowerShell 运行命令，或用 set /p content=<db.json 方式在 cmd 下写入。

5. wrangler.toml name 字段未放顶层导致发布报错

  • 问题：You need to provide a name when publishing a worker.
  • 解决：name = “xxx” 放到 wrangler.toml 顶层。

6. Worker 代码兼容 KV 读取

  • 问题：原先代码只支持环境变量或本地文件，云端无法读取大数据。
  • 解决：Worker 代码改为： 
    1
2

    const dbStr = await env.DB.get('DB_JSON');
const db = JSON.parse(dbStr);

7. 验证 KV 数据完整性

  • 问题：命令行输出被截断，无法确认数据是否完整。
  • 解决：
    • 用 Worker 代码直接返回 KV 内容到浏览器查看。
    • 或用 Cloudflare Dashboard 查看 KV。

本文档总结了 Cloudflare Workers + KV mock API 部署全流程常见问题与解决办法，适用于大体积 mock 数据的无后端前端项目部署。