CloudflareWorkersKV键值存储技能 cloudflare-kv

---

名称: cloudflare-kv 描述: Cloudflare Workers KV 全局键值存储。用于命名空间、缓存、TTL，或处理 KV_ERROR、429 速率限制、一致性问题。

关键词: kv 存储, cloudflare kv, workers kv, kv 命名空间, kv 绑定, kv 缓存, kv ttl, kv 元数据, kv 列表, kv 分页, 缓存优化, 边缘缓存, KV_ERROR, 429 请求过多, kv 速率限制, 最终一致性, wrangler kv, kv 操作, 键值存储 许可证: MIT 元数据: 版本: “3.0.0” 最后验证: “2025-12-27” 生产测试: true 令牌节省: “~60%” 错误预防: 5 包含模板: 5 包含参考: 7

Cloudflare Workers KV

状态: 生产就绪 ✅ | 最后验证: 2025-12-27

---

什么是 Workers KV？

Cloudflare 边缘的全局键值存储：

• 最终一致性
• 全球低延迟
• 支持 1GB+ 值
• TTL 过期
• 元数据支持

---

快速开始（5 分钟）

1. 创建 KV 命名空间

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

2. 配置绑定

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

3. 基本操作

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 获取完整设置。

---

KV API 方法

put() - 写入

// 基本
await env.MY_NAMESPACE.put('key', 'value');

// 带 TTL（1 小时）
await env.MY_NAMESPACE.put('key', 'value', {
  expirationTtl: 3600
});

// 带过期时间戳
await env.MY_NAMESPACE.put('key', 'value', {
  expiration: Math.floor(Date.now() / 1000) + 3600
});

// 带元数据
await env.MY_NAMESPACE.put('key', 'value', {
  metadata: { role: 'admin', created: Date.now() }
});

get() - 读取

// 简单获取
const value = await env.MY_NAMESPACE.get('key');

// 带类型
const text = await env.MY_NAMESPACE.get('key', 'text');
const json = await env.MY_NAMESPACE.get('key', 'json');
const buffer = await env.MY_NAMESPACE.get('key', 'arrayBuffer');
const stream = await env.MY_NAMESPACE.get('key', 'stream');

// 带元数据
const { value, metadata } = await env.MY_NAMESPACE.getWithMetadata('key');

delete() - 删除

await env.MY_NAMESPACE.delete('key');

list() - 列出键

// 基本列表
const { keys } = await env.MY_NAMESPACE.list();

// 带前缀
const { keys } = await env.MY_NAMESPACE.list({
  prefix: 'user:',
  limit: 100
});

// 分页
const { keys, cursor } = await env.MY_NAMESPACE.list({
  cursor: previousCursor
});

---

关键规则

总是做 ✅

1. 使用 TTL 处理临时数据
2. 处理 null（键可能不存在）
3. 使用元数据 存储小数据
4. 分页列表（最多 1000 键）
5. 使用前缀 组织数据
6. 在 Worker 中缓存（避免多次 KV 调用）
7. 使用 waitUntil() 处理异步写入
8. 处理最终一致性
9. 监控速率限制
10. 使用 JSON.stringify 处理对象

绝不做 ❌

1. 绝不要假设即时一致性
2. 绝不要超过 25MB 每个值
3. 绝不要列出所有键 无分页
4. 绝不要跳过错误处理
5. 绝不要用于实时数据
6. 绝不要超过速率限制（1000 写入/秒）
7. 绝不要存储未加密的秘密
8. 绝不要用作数据库（无事务）
9. 绝不要忽略元数据限制（1024 字节）
10. 绝不要跳过 TTL 处理临时数据

---

常见用例

用例 1: API 响应缓存

const cacheKey = `api:${url}`;
let cached = await env.MY_NAMESPACE.get(cacheKey, 'json');

if (!cached) {
  cached = await fetch(url).then(r => r.json());
  await env.MY_NAMESPACE.put(cacheKey, JSON.stringify(cached), {
    expirationTtl: 300  // 5 分钟
  });
}

return Response.json(cached);

用例 2: 用户偏好

const userId = '123';
const preferences = {
  theme: 'dark',
  language: 'en'
};

await env.MY_NAMESPACE.put(
  `user:${userId}:preferences`,
  JSON.stringify(preferences),
  {
    metadata: { updated: Date.now() }
  }
);

用例 3: 速率限制

const key = `ratelimit:${ip}`;
const count = parseInt(await env.MY_NAMESPACE.get(key) || '0');

if (count >= 100) {
  return new Response('超过速率限制', { status: 429 });
}

await env.MY_NAMESPACE.put(key, String(count + 1), {
  expirationTtl: 60  // 1 分钟窗口
});

用例 4: 带前缀的列表

const { keys } = await env.MY_NAMESPACE.list({
  prefix: 'user:',
  limit: 100
});

const users = await Promise.all(
  keys.map(({ name }) => env.MY_NAMESPACE.get(name, 'json'))
);

用例 5: waitUntil() 模式

export default {
  async fetch(request, env, ctx) {
    // 不等待 KV 写入
    ctx.waitUntil(
      env.MY_NAMESPACE.put('analytics', JSON.stringify(data))
    );

    return new Response('OK');
  }
};

---

限制（摘要）

键限制:

• 键大小: 最大 512 字节
• 值大小: 最大 25 MB
• 元数据: 最大 1024 字节

速率限制:

• 写入: 每键 1000/秒
• 列表: 每命名空间 100/秒
• 读取: 无限制

详细限制、定价和优化策略，请加载 references/limits-quotas.md

---

最终一致性

KV 是最终一致性:

• 写入全球传播约 60 秒
• 不适用于实时数据
• 使用 D1 实现强一致性

模式:

// 写入
await env.MY_NAMESPACE.put('key', 'value');

// 可能不会立即在其他区域可见
const value = await env.MY_NAMESPACE.get('key');  // 可能为 null

---

何时加载参考

根据任务上下文加载特定参考文件：

用于设置与配置:

• 加载 references/setup-guide.md 当创建命名空间或配置绑定时

用于性能优化:

• 加载 references/best-practices.md 当实施缓存或优化性能时
• 加载 references/performance-tuning.md 用于高级优化场景、cacheTtl 策略或基准测试

用于 API 使用:

• 加载 references/workers-api.md 当实施 KV 操作或需要方法签名时

用于故障排除:

• 加载 references/troubleshooting.md 当调试错误或一致性问题时

用于限制与配额:

• 加载 references/limits-quotas.md 当规划容量或遇到配额错误时

用于迁移:

• 加载 references/migration-guide.md 当从 localStorage、Redis、D1、R2 或其他存储解决方案迁移时

---

资源

参考 (references/):

• best-practices.md - 生产模式、缓存策略、速率限制处理、错误恢复
• setup-guide.md - 完整设置，包括 Wrangler CLI 命令、命名空间创建、绑定配置
• workers-api.md - 完整 API 参考、一致性模型（最终一致性）、限制与配额、性能优化
• troubleshooting.md - 综合错误目录与解决方案
• limits-quotas.md - 详细限制、配额、定价和优化技巧
• migration-guide.md - 完整迁移指南，从 localStorage、Redis、D1、R2 和其他存储解决方案
• performance-tuning.md - 高级 cacheTtl 策略、批量操作、键设计、基准测试技术

模板 (templates/):

• kv-basic-operations.ts - 基本 KV 操作（获取、写入、删除、列表）
• kv-caching-pattern.ts - 使用 KV 的 HTTP 缓存
• kv-list-pagination.ts - 带游标分页的列表
• kv-metadata-pattern.ts - 元数据使用模式
• wrangler-kv-config.jsonc - KV 命名空间绑定

脚本 (scripts/):

• check-versions.sh - 验证 KV API 端点和包版本
• test-kv-connection.sh - 测试 KV 命名空间连接和操作
• setup-kv-namespace.sh - 交互式命名空间设置向导
• validate-kv-config.sh - 验证 wrangler.jsonc 配置
• analyze-kv-usage.sh - 分析代码中的 KV 使用模式和优化

命令:

• /cloudflare-kv:setup - 交互式 KV 命名空间设置向导
• /cloudflare-kv:test - 测试 KV 操作和连接
• /cloudflare-kv:optimize - 分析和优化 KV 使用

代理:

• kv-optimizer - 分析 KV 使用并建议性能优化
• kv-debugger - 帮助调试 KV 错误和一致性问题

示例 (examples/):

• rate-limiting/ - 完整速率限制实现（固定窗口、滑动窗口、令牌桶、多层级）
• session-management/ - 生产会话存储，带 TTL 过期、元数据跟踪和管理控制
• api-caching/ - HTTP 响应缓存模式（旁路缓存、陈旧-验证、条件缓存、ETag）
• config-management/ - 功能标志、A/B 测试、环境配置、版本跟踪、热重载

---

官方文档

• KV 概述: https://developers.cloudflare.com/kv/
• KV API: https://developers.cloudflare.com/kv/api/
• 最佳实践: https://developers.cloudflare.com/kv/best-practices/

---

有问题？遇到问题？

1. 检查 references/setup-guide.md 获取完整设置
2. 验证命名空间绑定配置
3. 处理最终一致性
4. 检查速率限制