Kv 说明文档

# Cloudflare Workers KV 全球分布式、最终一致性的键值存储，针对高读取量和低延迟进行了优化。 ## 概述 KV 提供： - 最终一致性（60秒全球传播） - 读取优化性能 - 每个键 25 MiB 的值限制 - 自动复制到 Cloudflare 边缘节点 - 元数据支持 (1024 字节) **使用场景：** 配置存储、用户会话、功能标志、缓存、A/B 测试 ## 何时使用 KV | 需求 | 建议 | |------|----------------| | 强一致性 | → [Durable Objects](../durable-objects/) | | SQL 查询 | → [D1](../d1/) | | 对象存储 (文件) | → [R2](../r2/) | | 高读取、低写入量 | → KV ✅ | | 全球亚 10ms 读取 | → KV ✅ | **快速对比：** | 特性 | KV | D1 | Durable Objects | |---------|----|----|-----------------| | 一致性 | 最终 | 强 | 强 | | 读取延迟 | <10ms | ~50ms | <1ms | | 写入限制 | 1次/秒/键 | 无限制 | 无限制 | | 使用场景 | 配置、缓存 | 关系型数据 | 协调 | ## 快速开始 bash wrangler kv namespace create MY_NAMESPACE # 将绑定添加到 wrangler.jsonc typescript // 写入 await env.MY_KV.put("key", "value", { expirationTtl: 300 }); // 读取 const value = await env.MY_KV.get("key"); const json = await env.MY_KV.get("config", "json"); ## 核心操作 | 方法 | 用途 | 返回值 | |--------|---------|---------| | `get(key, type?)` | 单个读取 | `string | null` | | `get(keys, type?)` | 批量读取 (≤100) | `Map` | | `put(key, value, options?)` | 写入 | `Promise` | | `delete(key)` | 删除 | `Promise` | | `list(options?)` | 列出键 | `{ keys, list_complete, cursor? }` | | `getWithMetadata(key)` | 获取值 + 元数据 | `{ value, metadata }` | ## 一致性模型 - **写入可见性：** 同一位置立即生效，全球 ≤60秒 - **读取路径：** 最终一致性 - **写入速率：** 每个键 1 次写入/秒（超过则返回 429） ## 阅读顺序 | 任务 | 阅读文件 | |------|---------------| | 快速开始 | README → configuration.md | | 实现功能 | README → api.md → patterns.md | | 调试问题 | gotchas.md → api.md | | 批量操作 | api.md (批量部分) → patterns.md | | 性能调优 | gotchas.md (性能) → patterns.md (缓存) | ## 本参考文档包含 - [configuration.md](./configuration.md) - wrangler.jsonc 设置、命名空间创建、TypeScript 类型 - [api.md](./api.md) - KV 方法、批量操作、cacheTtl、内容类型 - [patter