cloudflare-kv

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cloudflare Workers KV

Status: Production Ready ✅ | Last Verified: 2025-12-27

状态：已就绪可用于生产 ✅ | 最后验证时间：2025-12-27

What Is Workers KV?

什么是Workers KV？

Global key-value storage on Cloudflare edge:

Eventually consistent
Low latency worldwide
1GB+ values supported
TTL expiration
Metadata support

Cloudflare边缘节点上的全局键值存储：

最终一致性
全球低延迟
支持1GB+大小的值
TTL自动过期
支持元数据

Quick Start (5 Minutes)

快速入门（5分钟）

1. Create KV Namespace

1. 创建KV命名空间

bash

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

bash

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

2. Configure Binding

2. 配置绑定

jsonc

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

jsonc

{
  "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. Basic Operations

3. 基础操作

typescript

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);
  }
};

Load
references/setup-guide.md
for complete setup.

typescript

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 Methods

KV API方法

put() - Write

put() - 写入

typescript

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

typescript

// 基础用法
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() - Read

get() - 读取

typescript

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

typescript

// 简单读取
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() - Remove

delete() - 删除

typescript

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

typescript

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

list() - List Keys

list() - 列出键

typescript

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

typescript

// 基础列出
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
});

Critical Rules

重要规则

Always Do ✅

建议做法 ✅

Use TTL for temporary data
Handle null (key might not exist)
Use metadata for small data
Paginate lists (max 1000 keys)
Use prefixes for organization
Cache in Worker (avoid multiple KV calls)
Use waitUntil() for async writes
Handle eventual consistency
Monitor rate limits
Use JSON.stringify for objects

为临时数据设置TTL
处理null值（键可能不存在）
使用元数据存储小型数据
对列表进行分页（最多1000个键）
使用前缀组织键
在Worker中缓存（避免多次KV调用）
使用waitUntil()处理异步写入
处理最终一致性问题
监控速率限制
使用JSON.stringify存储对象

Never Do ❌

禁止做法 ❌

Never assume instant consistency
Never exceed 25MB per value
Never list all keys without pagination
Never skip error handling
Never use for real-time data
Never exceed rate limits (1000 writes/second)
Never store secrets unencrypted
Never use as database (no transactions)
Never ignore metadata limits (1024 bytes)
Never skip TTL for temporary data

不要假设即时一致性
不要存储超过25MB的值
不要不进行分页就列出所有键
不要跳过错误处理
不要用于实时数据存储
不要超过速率限制（1000次写入/秒）
不要未加密存储敏感信息
不要将其用作数据库（不支持事务）
不要忽略元数据大小限制（1024字节）
不要不为临时数据设置TTL

Common Use Cases

常见使用场景

Use Case 1: API Response Caching

使用场景1：API响应缓存

typescript

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);

typescript

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);

Use Case 2: User Preferences

使用场景2：用户偏好设置

typescript

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

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

typescript

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

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

Use Case 3: Rate Limiting

使用场景3：速率限制

typescript

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
});

typescript

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分钟窗口
});

Use Case 4: List with Prefix

使用场景4：前缀过滤列表

typescript

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'))
);

typescript

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'))
);

Use Case 5: waitUntil() Pattern

使用场景5：waitUntil()模式

typescript

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');
  }
};

typescript

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

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

Limits (Summary)

限制汇总

Key Limits:

Key size: 512 bytes max
Value size: 25 MB max
Metadata: 1024 bytes max

Rate Limits:

Writes: 1000/sec per key
List: 100/sec per namespace
Reads: Unlimited

For detailed limits, pricing, and optimization strategies, load
references/limits-quotas.md

键值限制：

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

速率限制：

写入：每个键1000次/秒
列表查询：每个命名空间100次/秒
读取：无限制

详细限制、定价及优化策略请查看
references/limits-quotas.md

Eventual Consistency

最终一致性

KV is eventually consistent:

Writes propagate globally (~60 seconds)
Not suitable for real-time data
Use D1 for strong consistency

Pattern:

typescript

// 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

KV采用最终一致性：

写入操作会向全球节点同步（约60秒）
不适用于实时数据存储
需要强一致性请使用D1

示例模式：

typescript

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

// 在其他区域可能无法立即读取到
const value = await env.MY_NAMESPACE.get('key');  // 可能返回null

When to Load References

何时参考文档

Load specific reference files based on task context:

For Setup & Configuration:

Load
```
references/setup-guide.md
```
when creating namespaces or configuring bindings

For Performance Optimization:

Load
```
references/best-practices.md
```
when implementing caching or optimizing performance
Load
```
references/performance-tuning.md
```
for advanced optimization scenarios, cacheTtl strategies, or benchmarking

For API Usage:

Load
```
references/workers-api.md
```
when implementing KV operations or need method signatures

For Troubleshooting:

Load
```
references/troubleshooting.md
```
when debugging errors or consistency issues

For Limits & Quotas:

Load
```
references/limits-quotas.md
```
when planning capacity or encountering quota errors

For Migration:

Load
```
references/migration-guide.md
```
when migrating from localStorage, Redis, D1, R2, or other storage solutions

根据任务场景选择对应的参考文件：

设置与配置：

创建命名空间或配置绑定时，请查看
```
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
```

Resources

资源

References (

references/

```
best-practices.md
```
- Production patterns, caching strategies, rate limit handling, error recovery
```
setup-guide.md
```
- Complete setup with Wrangler CLI commands, namespace creation, bindings configuration
```
workers-api.md
```
- Complete API reference, consistency model (eventual consistency), limits & quotas, performance optimization
```
troubleshooting.md
```
- Comprehensive error catalog with solutions
```
limits-quotas.md
```
- Detailed limits, quotas, pricing, and optimization tips
```
migration-guide.md
```
- Complete migration guides from localStorage, Redis, D1, R2, and other storage solutions
```
performance-tuning.md
```
- Advanced cacheTtl strategies, bulk operations, key design, benchmarking techniques

Templates (

templates/

```
kv-basic-operations.ts
```
- Basic KV operations (get, put, delete, list)
```
kv-caching-pattern.ts
```
- HTTP caching with KV
```
kv-list-pagination.ts
```
- List with cursor pagination
```
kv-metadata-pattern.ts
```
- Metadata usage patterns
```
wrangler-kv-config.jsonc
```
- KV namespace bindings

Scripts (

scripts/

```
check-versions.sh
```
- Validate KV API endpoints and package versions
```
test-kv-connection.sh
```
- Test KV namespace connection and operations
```
setup-kv-namespace.sh
```
- Interactive namespace setup wizard
```
validate-kv-config.sh
```
- Validate wrangler.jsonc configuration
```
analyze-kv-usage.sh
```
- Analyze code for KV usage patterns and optimizations

Commands:

```
/cloudflare-kv:setup
```
- Interactive KV namespace setup wizard
```
/cloudflare-kv:test
```
- Test KV operations and connection
```
/cloudflare-kv:optimize
```
- Analyze and optimize KV usage

Agents:

```
kv-optimizer
```
- Analyzes KV usage and suggests performance optimizations
```
kv-debugger
```
- Helps debug KV errors and consistency issues

Examples (

examples/

```
rate-limiting/
```
- Complete rate limiting implementation (fixed window, sliding window, token bucket, multi-tier)
```
session-management/
```
- Production session store with TTL expiration, metadata tracking, and admin controls
```
api-caching/
```
- HTTP response caching patterns (cache-aside, stale-while-revalidate, conditional caching, ETag)
```
config-management/
```
- Feature flags, A/B testing, environment configs, version tracking, hot-reload

参考文档（

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基础操作（get、put、delete、list）
```
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使用方式

Agent：

```
kv-optimizer
```
- 分析KV使用情况并提供性能优化建议
```
kv-debugger
```
- 帮助调试KV错误及一致性问题

示例（

examples/

）：

```
rate-limiting/
```
- 完整的速率限制实现（固定窗口、滑动窗口、令牌桶、多层限制）
```
session-management/
```
- 生产级会话存储，支持TTL过期、元数据跟踪及管理员控制
```
api-caching/
```
- HTTP响应缓存模式（缓存回源、 stale-while-revalidate、条件缓存、ETag）
```
config-management/
```
- 功能开关、A/B测试、环境配置、版本跟踪、热重载

Official Documentation

官方文档

KV Overview: https://developers.cloudflare.com/kv/
KV API: https://developers.cloudflare.com/kv/api/
Best Practices: https://developers.cloudflare.com/kv/best-practices/

Questions? Issues?

Check
```
references/setup-guide.md
```
for complete setup
Verify namespace binding configured
Handle eventual consistency
Check rate limits

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

有疑问或问题？

查看
```
references/setup-guide.md
```
获取完整设置说明
验证命名空间绑定是否配置正确
处理最终一致性问题
检查速率限制