cloudflare-kv

用途

Cloudflare Workers KV 是 Cloudflare 提供的全球分布式键值（Key-Value）存储服务，构建在 Cloudflare 边缘网络之上。它适用于读多写少的工作负载，典型用途包括：缓存 API 响应、存储配置信息、管理用户偏好、功能开关（feature flags）等。官方建议的理想读写比约为 100:1。

不适合的场景：金融交易、需要强一致性的数据、单键每秒超过 1 次的写入、关键业务数据。若需要强一致性，应改用 Durable Objects。

主要能力

读写操作：通过 get 读取单个键，支持 string、json、arrayBuffer、stream 等类型；通过 put 写入值，可设置过期时间（expirationTtl 或 expiration）和元数据（metadata）。

批量读取：get(['key1', 'key2']) 可在单次请求中读取最多 100 个键，计为 1 次操作。

边缘缓存：读取时可设置 cacheTtl（最小 60 秒），将数据缓存在边缘节点，降低冷键读取延迟。

元数据优化：可将小于 1024 字节的小值存入 metadata，list() 会自动返回元数据，避免额外的 get() 调用。

列表与分页：list() 支持 prefix 前缀过滤、limit 和 cursor 游标分页。必须检查 list_complete 字段而非 keys.length === 0 来判断是否结束。

删除：delete() 删除单个键（总是成功）；CLI 支持批量删除（最多 10,000 个键）。

性能特性：热键（每数据中心每分钟读取 2 次以上）响应约 6-8ms；冷键约 100-300ms。2025 年 8 月架构重构后，所有 KV Worker 调用的 P90 低于 12ms，热读最高提速 3 倍。

使用方式

创建命名空间：

npx wrangler kv namespace create MY_NAMESPACE

在 wrangler.jsonc 中绑定：

{
  "kv_namespaces": [{
    "binding": "MY_NAMESPACE",
    "id": "<production-uuid>",
    "preview_id": "<preview-uuid>"
  }]
}

基本读写示例：

type Bindings = { MY_NAMESPACE: KVNamespace };

app.post('/set/:key', async (c) => {
  await c.env.MY_NAMESPACE.put(c.req.param('key'), await c.req.text());
  return c.json({ success: true });
});

app.get('/get/:key', async (c) => {
  const value = await c.env.MY_NAMESPACE.get(c.req.param('key'));
  return value ? c.json({ value }) : c.json({ error: 'Not found' }, 404);
});

Wrangler CLI 常用命令：

npx wrangler kv key put --binding=MY_KV "key" "value" [--ttl=3600] [--metadata='{}']
npx wrangler kv key get --binding=MY_KV "key" [--remote]
npx wrangler kv key list --binding=MY_KV [--prefix="user:"] [--remote]
npx wrangler kv key delete --binding=MY_KV "key"
npx wrangler kv bulk put --binding=MY_KV data.json
npx wrangler kv bulk delete --binding=MY_KV keys.json

注意：CLI 命令默认操作本地存储，需加 --remote 标志才能访问生产/远程数据。

本地开发连接生产 KV（Wrangler 4.37+）：在绑定中设置 "remote": true，本地 Worker 代码在本地执行，KV 操作通过代理路由到生产命名空间。警告：写入会影响生产数据，建议使用 staging 命名空间。

适用场景

缓存 API 响应（配合 cacheTtl）
存储应用配置和功能开关
管理用户偏好设置
读多写少的数据（100:1 读写比）
会话令牌等可容忍最终一致性的数据

限制与注意事项

配额限制：

键大小：最大 512 字节
值大小：最大 25 MiB
元数据：最大 1024 字节
单键写入速率：每秒 1 次（超出返回 429 错误）
过期时间：最小 60 秒
单次 Worker 调用操作数：最多 1,000
命名空间数量：每账户 1,000 个（2025 年 1 月从 200 提升）
免费计划：每天 100,000 次读取、1,000 次写入（不同键）、1 GB 存储；付费计划：读取和写入不限量、存储不限量

最终一致性：写入在同一位置（同一 POP）立即可见（read-your-own-write），其他位置约 60 秒内可见。缓存读取在传播期间可能返回旧数据。

关键规则：

读取多个键时使用批量操作（计为 1 次操作）
为频繁读取、不常更新的数据设置 cacheTtl（最小 60 秒）
分页时检查 list_complete，不要用 keys.length === 0
写入操作使用指数退避重试逻辑
写入前验证大小
合并相关键以提升缓存性能
不要假设全局立即一致
不要将命名空间 ID 提交到公开仓库

常见错误处理：429 速率限制（使用指数退避重试）、值过大（写入前校验）、元数据过大（校验序列化后大小）、cacheTtl 小于 60 秒（会失败）。

已知问题：wrangler types 不为环境嵌套的 KV 绑定生成类型（可用 npx wrangler types -e feature 或改为顶层定义）；wrangler kv key list 默认返回本地空数组（需加 --remote）。

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项