用途:Cloudflare Workers KV 是全局、低延迟、最终一致的键值存储,面向高读取、低写入的工作负载。
主要能力:通过命名空间与绑定在 Worker 中访问;Workers API 提供 put、get、getWithMetadata、list、delete,支持文本、JSON、ArrayBuffer、Stream 类型,多键读取(单次最多 100 键),list 支持 prefix、limit、cursor 分页。put 支持 expirationTtl(相对秒数,最小 60)、expiration(Unix 时间戳)与 metadata(最大 1024 字节 JSON)。读取支持 cacheTtl 控制边缘缓存时长。
使用方式:创建命名空间 npx wrangler kv namespace create MY_KV,在 wrangler.jsonc 或 wrangler.toml 中配置 kv_namespaces 绑定(binding、id、可选 preview_id、remote)。Wrangler 命令可执行 key put/get/delete/list 及 bulk put/bulk delete;批量操作仅支持 Wrangler 或 REST API,不支持 Workers 绑定。本地开发默认使用本地 KV,wrangler dev --remote 或 remote: true 使用远程 KV。
适用场景:静态配置、会话令牌、文件元数据、按前缀组织的用户数据等读多写少场景。
限制:最终一致,写入约 60 秒内全局传播;同一键写入速率上限 1 次/秒,超出返回 429;键最大 512 字节,值最大 25 MiB,元数据 1024 字节;list 单次最多 1000 键;批量单请求最多 10000 键、100 MB。需要强一致、原子操作、事务或高频写同一键时应改用 Durable Objects。免费与付费计划的读写、存储额度及超额计费资料中已列出,具体以官方为准。