Cloudflare KV 中文文档

本文参照 Cloudflare 官方手册结构，对 Workers KV 做系统化梳理（数据截至 2026-10，配额/价格以官方最新页面为准）。技术术语保留英文原词以便对照官方资料。

1. 概述

Cloudflare Workers KV 是一个全球、低延迟的键值存储，适合高读取量、低延迟的动态 API 与网站。它面向「读多写少」的场景，例如缓存 API 响应、存用户配置/偏好、存鉴权信息。Free 与 Paid 计划均可用。

一句话定位：全球分布的键值存储，为读多写少、低延迟的访问而设计。

2. 核心概念

2.1 Namespace（命名空间）

KV 数据组织在命名空间中，每个命名空间是一组键值的集合。每账户最多 1,000 个命名空间；命名空间内键数无限。

2.2 最终一致性（Eventual Consistency）

KV 是最终一致的：一次写入被放入队列，通常在数秒内传播到全球边缘节点（多数情况下更快）。因此刚写入后短时间内，某些区域可能仍读到旧值。它不适合需要强一致、写后立即读的实时数据——这类需求应选 D1 或 Durable Objects。

2.3 TTL（过期）

键可设置过期时间，到期自动删除。最小 cacheTtl 为 30 秒。

2.4 Jurisdictions（数据属地）

可把命名空间限制在特定司法辖区，数据只在该辖区内持久化，以帮助满足合规要求。

3. 架构与工作原理

• KV 把数据复制到全球边缘，读请求就近命中，因此读取延迟低。
• 写入后异步全球传播，所以存在短暂不一致窗口。
• 在 Worker 中通过 Binding 访问，也支持 REST API 供外部应用访问。

4. 快速开始

# 1. 创建命名空间
wrangler kv namespace create my-kv

# 2. 在 Worker 中绑定（见第 5 节）
wrangler deploy

5. 使用方式（API）

在 wrangler.jsonc 中绑定：

{
  "kv_namespaces": [
    { "binding": "KV", "id": "<namespace-id>" }
  ]
}

基础读写：

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // 写入（可设过期）
    await env.KV.put("site:ctx", JSON.stringify({ name: "yuebin" }), {
      expirationTtl: 86400,
    });

    // 读取（指定解析类型）
    const cfg = await env.KV.get("site:ctx", { type: "json" });
    const raw = await env.KV.get("site:ctx"); // 默认返回字符串

    // 列举（注意：list 较贵，谨慎使用）
    const { keys } = await env.KV.list();

    // 删除
    await env.KV.delete("site:ctx");

    return Response.json({ cfg });
  },
} satisfies ExportedHandler<Env>;

注意：list** 操作成本较高**，且每次列举都消耗配额；需要批量列举的逻辑应优先用 Cache API 或 D1。

6. 配额与限制

其他硬性限制（Free/Paid 相同）：

• 键（key）大小 ≤ 512 字节；键元数据 ≤ 1,024 字节。
• 值（value）大小 ≤ 25 MiB。
• 最小 cacheTtl：30 秒。
• 命名空间内键数：无限。

Workers KV Instant（测试版）：写 1 次/秒、存储 1 MB、键 10,000、键大小 300 字节、不支持元数据、值大小受 1 MB 总容量约束、不支持列表分页。

7. 定价

• Free 计划含上表免费额度；Paid 计划读取/写入/存储无限（按 KV 计价，以官方定价页为准）。

8. 最佳实践

• 只放「读多写少」的小配置；别把需要频繁列举的数据放进来。
• **慎用 **list：优先 Cache API / D1。任何「列举一堆键」的逻辑（如批量缓存、侧边栏、RSS）都容易打满配额。
• 注意最终一致性——不要依赖「写入后立即全局读到」。
• 单个值 ≤ 25 MiB；键 ≤ 512 字节；同一 key 写入 ≤ 1 次/秒。

9. 适用场景与选型

• 缓存 API 响应、站点配置快照、用户配置/偏好、鉴权细节。
• 跨 isolate 共享的小体积、读多写少的配置。
• 需要强一致的状态协调（如计数器、会话）→ 考虑 Durable Objects。
• 需要 SQL 关系查询 → 选 D1；需要存大文件/媒体 → 选 R2。