用途:基于 Cloudflare KV 在边缘网络存储键值数据,适用于缓存 API 响应、存储配置、管理用户偏好、处理会话等读写远多于写入的场景。依赖 cloudflare-worker-base 完成 Worker 初始化。
主要能力:通过 KV 绑定在 Worker 中读写数据。读取支持 get()(text、json、arrayBuffer、stream 类型)、批量 get(keys[])(仅 text 与 json)、getWithMetadata() 与 getWithMetadata(keys[]),可用 cacheTtl 做边缘缓存。写入使用 put(),支持 expirationTtl 或绝对 expiration,以及 metadata。列出使用 list(),支持 prefix、limit 与 cursor 分页。删除使用 delete()。
使用方式:先用 npx wrangler kv namespace create MY_NAMESPACE 创建命名空间(开发可用 --preview),把返回的命名空间 ID 写入 wrangler.jsonc 或 wrangler.toml 的 kv_namespaces 绑定(binding、id、可选 preview_id),在代码中通过 env.MY_NAMESPACE 访问。也可用 wrangler kv key put/get/list/delete 及 bulk put/bulk delete 操作数据。
限制与注意:key 最大 512 字节,value 最大 25 MiB,metadata 最大 1024 字节,单 key 写入速率上限 1 次/秒,过期最短 60 秒;cacheTtl 最小 60 秒。list() 每次最多 1000 个 key,需根据 list_complete 与 cursor 翻页,使用 prefix 分页时每次请求都要带相同 prefix。KV 最终一致:同位置写入立即可见,其他位置约 60 秒内传播,可能读到旧值,不适合强一致、原子操作或高频写同一 key 的场景,此类需求应使用 Durable Objects。批量删除 Worker 绑定不支持,可走 REST API,单次最多 10000 个 key;绑定方式不支持批量删除。