cloudflare-kv

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) {
    // Write
    await env.MY_NAMESPACE.put('key', 'value');

    // Read
    const value = await env.MY_NAMESPACE.get('key');

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

    return new Response(value);
  }
};

加载 references/setup-guide.md 查看完整的设置指南。

---

KV API 方法

put() - 写入

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

// With TTL (1 hour)
await env.MY_NAMESPACE.put('key', 'value', {
  expirationTtl: 3600
});

// With expiration timestamp
await env.MY_NAMESPACE.put('key', 'value', {
  expiration: Math.floor(Date.now() / 1000) + 3600
});

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

get() - 读取

// Simple get
const value = await env.MY_NAMESPACE.get('key');

// With type
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');

// With metadata
const { value, metadata } = await env.MY_NAMESPACE.getWithMetadata('key');

delete() - 删除

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

list() - 列出键

// Basic list
const { keys } = await env.MY_NAMESPACE.list();

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

// Pagination
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 minutes
  });
}

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('Rate limit exceeded', { status: 429 });
}

await env.MY_NAMESPACE.put(key, String(count + 1), {
  expirationTtl: 60  // 1 minute window
});

用例 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) {
    // Don't wait for KV write
    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

模式：

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

// May not be visible immediately in other regions
const value = await env.MY_NAMESPACE.get('key');  // Might be null

---

何时加载参考资料

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

设置与配置：

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

性能优化：

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

API 使用：

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

故障排查：

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

限制与配额：

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

迁移：

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

---

资源

参考资料（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 命名空间绑定

脚本：

• 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 使用

Agent：

• 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. 检查速率限制