cloudflare-kv

用途

Cloudflare Workers KV 是 Cloudflare 边缘网络上的全局键值存储服务。本技能用于指导在 Cloudflare Workers 中使用 KV，包括命名空间管理、缓存、TTL 设置，以及处理 KV_ERROR、429 速率限制和一致性等问题。

主要能力

全局键值存储：最终一致性、全球低延迟、支持 1GB 以上值、TTL 过期、元数据支持。
提供 KV API 方法：put() 写入（支持 TTL、过期时间戳、元数据）、get() 读取（支持 text、json、arrayBuffer、stream 类型及 getWithMetadata）、delete() 删除、list() 列出键（支持前缀、limit、游标分页）。
常见用例：API 响应缓存、用户偏好存储、速率限制、前缀列表、waitUntil() 异步写入模式。
附带参考文档、模板、脚本、命令和智能体，覆盖设置、测试、优化、排错、迁移和性能调优。

使用方式

创建 KV 命名空间：

bunx wrangler kv namespace create MY_NAMESPACE
bunx wrangler kv namespace create MY_NAMESPACE --preview

配置绑定（wrangler 配置示例）：

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-10-11",
  "kv_namespaces": [
    {
      "binding": "MY_NAMESPACE",
      "id": "<PRODUCTION_ID>",
      "preview_id": "<PREVIEW_ID>"
    }
  ]
}

基本操作示例：

export default {
  async fetch(request, env, ctx) {
    await env.MY_NAMESPACE.put('key', 'value');
    const value = await env.MY_NAMESPACE.get('key');
    await env.MY_NAMESPACE.delete('key');
    return new Response(value);
  }
};

完整设置可加载 references/setup-guide.md。

关键规则

始终：为临时数据使用 TTL；处理 null（键可能不存在）；使用元数据存储小数据；分页列表（最多 1000 键）；使用前缀组织；在 Worker 内缓存以避免多次 KV 调用；使用 waitUntil() 处理异步写入；处理最终一致性；监控速率限制；用 JSON.stringify 处理对象。

避免：假设即时一致性；单值超过 25MB；无分页列出全部键；跳过错误处理；用于实时数据；超过速率限制（1000 写/秒）；未加密存储密钥；当作数据库使用（无事务）；忽略元数据限制（1024 字节）；临时数据不设 TTL。

适用场景

API 响应缓存（cache-aside、stale-while-revalidate、条件缓存、ETag）。
用户偏好、会话管理（带 TTL 过期、元数据跟踪、管理控制）。
速率限制（固定窗口、滑动窗口、令牌桶、多层级）。
配置管理（功能开关、A/B 测试、环境配置、版本跟踪、热重载）。

限制

键大小：最大 512 字节。
值大小：最大 25MB。
元数据：最大 1024 字节。
速率限制：写入 1000/秒每键；列表 100/秒每命名空间；读取无限制。
最终一致性：写入全球传播约 60 秒，不适合实时数据；强一致场景可使用 D1。

参考资源

技能包含 references/（best-practices.md、setup-guide.md、workers-api.md、troubleshooting.md、limits-quotas.md、migration-guide.md、performance-tuning.md）、templates/、scripts/、命令（/cloudflare-kv:setup、/cloudflare-kv:test、/cloudflare-kv:optimize）、智能体（kv-optimizer、kv-debugger）和 examples/。官方文档：https://developers.cloudflare.com/kv/ 、https://developers.cloudflare.com/kv/api/ 、https://developers.cloudflare.com/kv/best-practices/ 。