# Cloudflare Workers KV **状态**：生产就绪 ✅ **最后更新**：2025-10-21 **依赖项**：cloudflare-worker-base（用于 Worker 设置） **最新版本**：wrangler@4.43.0、@cloudflare/workers-types@4.20251014.0 ** ** ## 快速入门（5 分钟） ### 1\.创建KV命名空间 # 创建一个新的KV命名空间 npx 牧马人 kv 命名空间创建 MY_NAMESPACE # 输出包括namespace_id - 保存它！ # ✅ 成功！ # 将以下内容添加到 wrangler.toml 或 wrangler.jsonc 中： # # [[kv_命名空间]] # 绑定 = "MY_NAMESPACE" # id = "" **用于开发（预览）命名空间：** npx 牧马人 kv 命名空间创建 MY_NAMESPACE --preview # 输出： # [[kv_命名空间]] # 绑定 = "MY_NAMESPACE" # Preview_id = "" ### 2\.配置绑定添加到您的“wrangler.jsonc”： { “姓名”：“我的工人”， "main": "src/index.ts", “兼容性日期”：“2025-10-11”， “kv_命名空间”：[ { "binding": "MY_NAMESPACE", // 可用作 env.MY_NAMESPACE "id": "<生产-uuid>", // 生产命名空间 ID "preview_id": "" // 本地开发命名空间 ID（可选） } ] } **或者使用`wrangler.toml`:** 名称 =“我的工人” 主要=“src/index.ts” 兼容性_日期=“2025-10-11” [[kv_命名空间]] 绑定=“MY_NAMESPACE” id = "<生产-uuid>" Preview_id = "<预览-uuid>" # 可选 **关键：** * `binding` 是在代码中访问命名空间的方式 (`env.MY_NAMESPACE`) * `id` 是生产命名空间 UUID * `preview_id` 用于本地开发（可选，单独的命名空间） * **永远不要将真实的命名空间 ID 提交到公共存储库** \- 使用环境变量或机密 ### 3\.编写您的第一个键值对从'hono'导入{Hono}；类型绑定 = { MY_NAMESPACE：KV命名空间； }; const app = new Hono<{ 绑定: 绑定 }>(); app.post('/set/:key', async (c) => { const key = c.req.param('key'); const value =等待c.req.text(); // 简单写等待 c.env.MY_NAMESPACE.put(key, value); 返回 c.json({ success: true, key }); }); app.get('/get/:key', async (c) => { const key = c.req.param('key'); const value =等待c.env.MY_NAMESPACE.get(key); 如果（！值）{ return c.json({ 错误: '未找到' }, 404); } 返回 c.json({ 值 }); }); 导出默认应用程序； ### 4\.本地测试 # 启动本地开发服务器 npm 运行开发 # 在另一个终端中，测试端点 curl -X POST http://localhost:8787/set/test -d "Hello KV" # {"成功":true,"关键":"测试"} 卷曲 http://localhost:8787/get/test # {"value":"你好 KV"} ** ** ## 完整的 Workers KV API ### 1\.读操作 #### `get()` \- 读取单个密钥 // 获取字符串（默认）常量值：字符串| null =等待env.MY_KV.get('my-key'); // 获取 JSON 格式常量数据：MyType | null = wait env.MY_KV.get('my-key', { type: 'json' }); // 获取ArrayBuffer 常量缓冲区：ArrayBuffer | null = wait env.MY_KV.get('my-key', { type: 'arrayBuffer' }); // 获取为 ReadableStream const 流：ReadableStream | null = wait env.MY_KV.get('my-key', { type: 'stream' }); // 通过缓存优化获取 const value = wait env.MY_KV.get('my-key', { 类型：'文本'， cacheTtl: 300, // 在边缘缓存 5 分钟（最少 60 秒） }); #### `get()` \- 读取多个键（批量） // 一次读取多个键（计为 1 次操作） const 键 = ['key1', 'key2', 'key3']; 常量值：Map<字符串，字符串| null> = 等待 env.MY_KV.get(keys); // 访问值 const value1 = value.get('key1'); // 字符串 |空 const value2 = value.get('key2'); // 字符串 |空 // 转换为对象 const obj = Object.fromEntries(values); #### `getWithMetadata()` \- 使用元数据读取 // 获取带有元数据的单个密钥 const { 值，元数据 } =等待 env.MY_KV.getWithMetadata('my-key'); // 值：字符串 |空 // 元数据：任意 |空 // 获取带有元数据的 JSON const { 值，元数据 } =等待 env.MY_KV.getWithMetadata('my-key', { 类型：'json'，缓存时间：300， }); // 获取带有元数据的多个键 const 键 = ['key1', 'key2']; const 结果: Map = 等待 env.MY_KV.getWithMetadata(keys); for (结果的 const [键, 数据]) { console.log(key, data.value, data.metadata); } **类型选项：** * `text` （默认）- 返回 `string` * `json` \- 解析 JSON，返回 `object` * `arrayBuffer` \- 返回 `ArrayBuffer` * `stream` \- 返回 `ReadableStream` **注意：** 使用 `get(keys[])` 批量读取仅支持 `text` 和 `json` 类型。对于“arrayBuffer”或“stream”，请使用单独的“get()”调用和“Promise.all()”。 ** ** ### 2\.写操作 #### `put()` \- 写入键值对 // 简单写等待 env.MY_KV.put('key', 'value'); // 写入 JSON 等待 env.MY_KV.put('用户:123', JSON.stringify({ name: 'John', 年龄: 30 })); // 写有过期时间（TTL）等待 env.MY_KV.put('会话：abc', sessionData, { expirationTtl: 3600, // 1小时后过期（最少60秒） }); // 绝对过期写入 const过期时间 = Math.floor(Date.now() / 1000) + 86400; // 24 小时后等待 env.MY_KV.put('token', tokenValue, { expiration:expirationTime, // 自纪元以来的秒数 }); // 使用元数据写入等待 env.MY_KV.put('配置：主题', '黑暗', { 元数据：{ 更新时间：Date.now(), 更新者：'管理员'，版本：2 }, }); // 写所有的东西等待 env.MY_KV.put('feature:flags', JSON.stringify(flags), { 过期时间：600，元数据: { 来源: 'api', 时间戳: Date.now() }, }); **关键限制：** * **密钥大小**：最大 512 字节 * **值大小**：最大 25 MiB * **元数据大小**：最大 1024 字节（JSON 序列化） * **写入速率**：每键每秒最多写入 1 次** * **最小过期**：60 秒（TTL 和绝对） **速率限制处理：** 异步函数 putWithRetry( kv：KV命名空间，键：字符串，值：字符串，选项？：KVPutOptions ）{ 让尝试= 0；常量最大尝试次数= 5；让延迟= 1000； // 从1秒开始 while (尝试次数 < maxAttempts) { 尝试{ 等待 kv.put(键、值、选项); 返回; // 成功 } 捕获（错误）{ const message = (错误作为错误).message; if (message.includes('429') || message.includes('太多请求')) { 尝试++； if (尝试次数 >= maxAttempts) { throw new Error('达到最大重试次数'); } console.warn(`尝试 ${attempts} 失败。在 ${delay} 毫秒后重试...`); 等待新的 Promise(解决 => setTimeout(解决, 延迟)); // 指数退避延迟*= 2； } 否则{ 抛出错误； // 不同的错误，重新抛出 } } } } ** ** ### 3\.列表操作 #### `list()` \- 列表键 // 列出所有键（最多 1000 个） const 结果 = 等待 env.MY_KV.list(); console.log(结果.keys); // 关键对象数组 console.log(结果.list_complete); // boolean - 如果存在更多键则为 false console.log(结果.光标); // 字符串 - 用于分页 // 带前缀过滤器的列表 const 结果 = 等待 env.MY_KV.list({ prefix: 'user:', // 仅限以 'user:' 开头的键 }); // 有限制的列表 const 结果 = 等待 env.MY_KV.list({ limit: 100, // 最大 1000 (默认 1000) }); // 用光标分页让光标：字符串|不明确的; 让 allKeys: 任何[] = []; 做{ const 结果 = 等待 env.MY_KV.list({ 光标 }); allKeys = allKeys.concat(结果.keys); 光标 = 结果.list_complete ？未定义：结果.光标； while（光标）； // 组合：前缀+分页让光标：字符串|不明确的; const userKeys: 任何[] = []; 做{ const 结果 = 等待 env.MY_KV.list({ 前缀：'用户：'，光标， }); userKeys.push(...result.keys); 光标 = 结果.list_complete ？未定义：结果.光标； while（光标）； **列出响应格式：** { 键：[ { 名称：“用户：123”， expiration: 1234567890, // 可选：自纪元以来的秒数元数据: { ... } // 可选：元数据对象 }, // ...更多键 ], list_complete: false, // 如果没有更多键则为 true 光标: "6Ck1la0VxJ0djhidm1MdX2FyD" // 用于下一页 } **重要：** * 键**总是**按字典顺序返回（UTF-8） * **始终检查`list_complete`**，而不是`keys.length === 0` * 空的`keys`数组并不意味着没有更多的数据（过期/删除的键会创建“墓碑”） * 使用“前缀”分页时，您**必须**为每个“光标”请求传递相同的“前缀” ** ** ### 4\.删除操作 #### `delete()` \- 删除键 // 删除单个键等待 env.MY_KV.delete('my-key'); // 即使键不存在，删除也总是成功等待 env.MY_KV.delete('不存在的密钥'); // 没有错误 // 批量删除模式（在 Worker 中） const keyToDelete = ['key1', 'key2', 'key3', ...]; // 并行删除（注意Worker子请求限制）等待 Promise.all( keyToDelete.map(key => env.MY_KV.delete(key)) ）； // 对于超过 1000 个键，使用 REST API 批量删除（通过 wrangler 或 API） **通过 REST API 批量删除：** Workers 绑定不支持批量删除，但您可以使用 REST API（通过“wrangler”或直接 API 调用）： # 使用牧马人 CLI npx wrangler kv 批量删除 --namespace-id= keys.json #keys.json格式： # [“键1”，“键2”，“键3”] **REST API 限制：** 每个批量删除请求最多 10,000 个键。 ** ** ## 高级模式和最佳实践 ### 1\.使用 CacheTtl 的缓存模式异步函数 getCachedData( kv：KV命名空间，缓存键：字符串， fetchFn: () => Promise<任意>, 缓存时间：数量 = 300 ）{ // 尝试从KV缓存中获取 const 缓存 = 等待 kv.get(cacheKey, { 类型：'json'， cacheTtl, // 在边缘缓存以加快后续读取速度 }); 如果（缓存）{ 返回缓存； } // 缓存未命中 - 获取新数据 const 数据 = 等待 fetchFn(); // 存储在KV中并有过期时间等待 kv.put(cacheKey, JSON.stringify(data), { expirationTtl:cacheTtl * 2, // 存储时间比缓存长 }); 返回数据； } // 用法 app.get('/api/data/:id', async (c) => { const id = c.req.param('id'); 常量数据 = 等待 getCachedData( c.env.CACHE， `数据：${id}`, () => 从数据库中获取(id), 300 // 5 分钟）；返回 c.json(数据); }); **CacheTtl 指南：** * **最短：** 60 秒 * **默认：** 60 秒 * **最大值：** `Number.MAX_SAFE_INTEGER` * **用例：** 经常读取、不经常更新的数据 * **权衡：** 较高的cacheTtl = 读取速度更快，但更新传播速度较慢 ** ** ### 2\.元数据优化模式在元数据中存储较小的值以避免单独的“get()”调用： // ❌ 不好：两个操作等待 env.MY_KV.put('用户:123', '活动'); const status = wait env.MY_KV.get('用户:123'); // ✅ 好：以空值存储在元数据中等待 env.MY_KV.put('用户:123', '', { 元数据：{ 状态：'活动'， LastSeen: Date.now(), 计划：“专业” }, }); // List自动返回元数据 const users = wait env.MY_KV.list({ 前缀: '用户:' }); users.keys.forEach(({ 名称, 元数据 }) => { console.log(名称、元数据.状态、元数据.计划); // 不需要额外的 get() 调用！ }); **何时使用：** * ✅ 值适合 1024 字节 * ✅ 您经常使用 `list()` 操作 * ✅ 你需要过滤/处理很多key * ❌ 不要用于大值（使用常规值存储） ** ** ### 3\.性能关键合并将相关冷键与热键组合： // ❌ 不好：许多单独的按键（有些热，有些冷）等待 kv.put('用户:123:姓名', '约翰'); 等待 kv.put('用户:123:电子邮件', 'john@example.com'); 等待 kv.put('用户:123:年龄', '30'); // ✅ 好：合并为单个热键等待 kv.put('用户:123', JSON.stringify({ 姓名：“约翰”，电子邮件：'john@example.com'，年龄：30岁， })); // 单次读取即可获取所有内容 const user = wait kv.get('user:123', { type: 'json' }); **优点：** * 冷键受益于热键缓存 * 更少的操作=更好的性能 * 单个缓存条目而不是多个 **缺点：** * 无法轻松更新单个字段（需要读取-修改-写入） * 较大的合并值可能会达到内存限制 * 并发更新需要锁定机制 ** ** ### 4\.分页助手异步函数* paginateKV( kv：KV命名空间，选项：{ 前缀？：字符串；限制？：数量 } = {} ）{ 让光标：字符串|不明确的; 做{ const 结果 = 等待 kv.list({ 前缀：选项.前缀，限制：选项.限制 || 1000, 光标， }); 产生结果.keys；光标 = 结果.list_complete ？未定义：结果.光标； while（光标）； } // 用法 app.get('/all-users', async (c) => { const allUsers = []; for等待（paginateKV的常量键（c.env.MY_KV，{前缀：'用户：'}））{ // 处理批次 allUsers.push(...keys.map(k => k.name)); } return c.json({ users: allUsers, count: allUsers.length }); }); ** ** ### 5\.特征标志模式接口功能标志{ 黑暗模式：布尔值；新仪表板：布尔值； beta 特性：布尔值； } 异步函数 getFeatureFlags( kv：KV命名空间，用户ID？：字符串 ): Promise { // 首先尝试用户特定的标志 if (用户ID) { const userFlags = wait kv.get(`flags:user:${userId}`, { 类型：'json'，缓存时间：300， }); if (userFlags) 返回 userFlags; } // 回退到全局标志 const globalFlags =等待 kv.get('flags:global', { 类型：'json'，缓存时间：300， }); 返回全局标志 || { 黑暗模式：假，新仪表板：假， beta特性：假， }; } // 更新全局标志 app.post('/admin/flags', async (c) => { const flags = wait c.req.json(); 等待 c.env.CONFIG.put('flags:global', JSON.stringify(flags), { 元数据：{updatedAt：Date.now（）}， }); 返回 c.json({ 成功: true }); }); ** ** ## 理解最终一致性 KV 在 Cloudflare 的全球网络中**最终一致**： ### 工作原理： 1. **写入**在**同一位置**立即可见 2. **其他位置**在**~60秒**内看到更新（或您的`cacheTtl`值） 3. **缓存读取**可能在传播过程中返回过时的数据 ### 影响： // 在东京数据中心：等待 env.MY_KV.put('计数器', '1'); const value1 = wait env.MY_KV.get('计数器'); //“1”✅ // 在伦敦数据中心（60秒内）： const value2 =等待env.MY_KV.get('计数器'); // 可能仍然是旧值 ⚠️ // 60 多秒后： const value3 =等待env.MY_KV.get('计数器'); //“1”✅ ### 最佳实践： ✅ **使用 KV 来：** * 读取密集型工作负载（100:1 读/写比） * 不需要立即全局一致性的数据 * 配置、功能标志、缓存 * 用户偏好、会话数据 ❌ **不要将 KV 用于：** * 需要原子操作的金融交易 * 需要强一致性的数据 * 高频写入同一键（>1/秒） * 过时读取不可接受的关键数据 **如果需要强一致性，请使用[Durable Objects]()。** ** ** ## Wrangler CLI 操作 ### 创建命名空间 # 生产命名空间 npx 牧马人 kv 命名空间创建 MY_NAMESPACE # 预览/开发命名空间 npx 牧马人 kv 命名空间创建 MY_NAMESPACE --preview ### 列出命名空间 npx wrangler kv 命名空间列表 ### 写入键值对 # 写入单个密钥 npx 牧马人 kv key put --binding=MY_NAMESPACE "my-key" "my-value" # 从文件写入 npx 牧马人 kv key put --binding=MY_NAMESPACE "config" --path=config.json # 使用元数据写入 npx 牧马人 kv key put --binding=MY_NAMESPACE "key" "value" --metadata='{"version":1}' # 使用 TTL（秒）写入 npx牧马人kv密钥放置--绑定= MY_NAMESPACE“会话”“数据”--ttl = 3600 ### 读取键值对 # 读取单个密钥 npx 牧马人 kv key get --binding=MY_NAMESPACE "my-key" # 读取到文件 npx 牧马人 kv key get --binding=MY_NAMESPACE "image" --path=image.png ### 列表键 # 列出所有键 npx 牧马人 kv 密钥列表 --binding=MY_NAMESPACE # 带前缀的列表 npx 牧马人 kv 密钥列表 --binding=MY_NAMESPACE --prefix="用户：" # 漂亮的打印 npx 牧马人 kv 密钥列表 --binding=MY_NAMESPACE | jq“.” ### 删除键 # 删除单个键 npx 牧马人 kv 密钥删除 --binding=MY_NAMESPACE "my-key" ### 批量操作 # 批量写入（最多 10,000 个键） npx 牧马人 kv 批量放置 --binding=MY_NAMESPACE data.json # 数据.json格式： # [ # {"key": "key1", "value": "value1"}, # {“键”：“键2”，“值”：“值2”，“expiration_ttl”：3600} #] # 批量删除（最多 10,000 个键） npx 牧马人 kv 批量删除 --binding=MY_NAMESPACE keys.json #keys.json格式： # [“键1”，“键2”，“键3”] ** ** ## 限制和配额特色 |免费计划 |付费计划 ---|---|--- **每天阅读** | 100,000 |无限 **每天写入**（不同键）| 1,000 |无限 **每秒每个键写入** | 1 | 1 **每个 Worker 调用的操作** | 1,000 | 1,000 **每个帐户的命名空间** | 1,000 | 1,000 **每个帐户的存储空间** | 1 GB |无限 **每个命名空间的存储** | 1 GB |无限 **每个命名空间的键** |无限 |无限 **钥匙尺寸** | 512 字节 | 512字节 **元数据大小** | 1024 字节 | 1024字节 **价值大小** | 25 MiB | 25 MiB 25 兆字节 **最小缓存Ttl** | 60 秒 | 60秒 **最大缓存Ttl** |数量.MAX_SAFE_INTEGER | Number.MAX_SAFE_INTEGER **重要说明：** * **每个键每秒 1 次写入** ：对同一键的并发写入会导致 429 错误 * **每次调用 1000 次操作**：批量操作计为 **1 次操作** * **批量读取**（读取多个键）算作单个操作 * **REST API** 受 [Cloudflare API 速率限制]() ** ** ## TypeScript 类型 // KVNamespace 类型由 @cloudflare/workers-types 提供接口 KV 命名空间 { get(key: string, options?: Partial>): Promise; get(key: string, type: "text"): Promise; get(key: string, type: "json"): Promise; get(key: string, type: "arrayBuffer"): Promise; get(key: string, type: "stream"): Promise; get(key: string, options?: KVGetOptions<"text">): Promise; 获取 (key: string, options?: KVGetOptions<"json">): Promise; get(key: string, options?: KVGetOptions<"arrayBuffer">): Promise; get(key: string, options?: KVGetOptions<"stream">): Promise; get(keys: string[]): Promise>; get(keys: string[], type: "text"): Promise>; get(keys: string[], type: "json"): Promise>; getWithMetadata(key: string, options?: Partial>): Promise>; getWithMetadata(key: string, type: "text"): Promise>; getWithMetadata(key: string, type: "json"): Promise>; getWithMetadata(key: string, options?: KVGetOptions<"text">): Promise>; getWithMetadata(key: string, options?: KVGetOptions<"json">): Promise>; getWithMetadata(keys: string[]): Promise>>; getWithMetadata(keys: string[], type: "text"): Promise>>; getWithMetadata(keys: string[], type: "json"): Promise>>; put(key: string, value: string | ArrayBuffer | ArrayBufferView | ReadableStream, options?: KVPutOptions): Promise; 删除（键：字符串）：Promise ；列表<元数据 = 未知>(选项？: KVListOptions): Promise>; } 接口 KVGetOptions<类型> { 类型：类型； cacheTtl？：数字； } 接口 KVGetWithMetadataResult<值，元数据> { 价值：价值|无效的; 元数据：元数据|无效的; } 接口 KVPutOptions { 过期？：数量； // 自纪元以来的秒数过期时间？：数字； // 从现在起的秒数（最少 60 秒）元数据？：任何； // 可序列化为 JSON，最大 1024 字节 } 接口 KVListOptions { 前缀？：字符串；限制？：数量； // 默认 1000，最大 1000 光标？：字符串； } 接口 KVListResult<元数据 = 未知> { 键：{ 名称：字符串；过期？：数量；元数据？：元数据； }[]; 列表完成：布尔值；光标？：字符串； } ** ** ## 错误处理 ### 常见错误 #### 1\.速率限制（429 请求过多）尝试{ 等待 env.MY_KV.put('计数器', '1'); 等待 env.MY_KV.put('计数器', '2'); // 太快了！ < 1 秒 } 捕获（错误）{ // 错误：KV PUT 失败：429 请求过多控制台.错误（错误）； } // 解决方案：使用带有退避的重试（参见上面的 putWithRetry 示例） #### 2\.值太大 const largeValue = 'x'.repeat(26 * 1024 * 1024); // > 25 MiB 尝试{ 等待 env.MY_KV.put('large', largeValue); } 捕获（错误）{ // 错误：值太大控制台.错误（错误）； } // 解决方案：写入前检查大小 if (值.长度 > 25 * 1024 * 1024) { throw new Error('值超过 25 MiB 限制'); } #### 3\.元数据太大 const 元数据 = { data: 'x'.repeat(2000) }; // > 1024 字节序列化尝试{ 等待 env.MY_KV.put('key', 'value', { 元数据 }); } 捕获（错误）{ // 错误：元数据太大控制台.错误（错误）； } // 解决方案：验证元数据大小 const 序列化 = JSON.stringify(元数据); if (serialized.length > 1024) { throw new Error('元数据超过 1024 字节限制'); } #### 4\.无效的缓存时间 // ❌ 太低等待 env.MY_KV.get('key', { cacheTtl: 30 }); // 错误：最小值为 60 // ✅ 正确等待 env.MY_KV.get('key', { cacheTtl: 60 }); ** ** ## 永远这样做 ✅ 1. **读取多个键时使用批量操作**（计为1次操作） 2. **为频繁读取、不频繁更新的数据设置cacheTtl** 3. **频繁使用 `list()` 时，在元数据中存储较小的值** 4. **分页时检查`list_complete`**，而不是`keys.length === 0` 5. **使用具有指数退避的重试逻辑**进行写入操作 6. **写入前验证大小**（密钥 512 字节，值 25 MiB，元数据 1 KB） 7. **使用预览命名空间**进行本地开发 8. **为缓存失效设置适当的 TTL**（至少 60 秒） 9. **合并相关键**以获得更好的缓存性能 10. **将 KV 用于读取密集型工作负载**（理想的读取/写入比率为 100:1） ** ** ## 永远不要这样做 ❌ 1. **永远不要写入相同的密钥 >1/秒** \- 导致 429 速率限制错误 2. **永远不要假设立即全局一致性** \- 传播大约需要 60 秒 3. **永远不要使用 KV 进行原子操作** \- 使用持久对象代替 4. **永远不要设置cacheTtl <60秒** \- 会失败 5. **永远不要将命名空间 ID 提交到公共存储库** \- 使用环境变量 6. **每次调用不要超过 1000 次操作** \- 使用批量操作 7. **永远不要依赖写入顺序** \- 最终一致性意味着不保证 8. **切勿在未加密的情况下存储敏感数据** \- KV 默认情况下不加密 9. **永远不要使用 KV 进行高频写入** \- 不适合写入密集型工作负载 10. **永远不要忘记处理 null 值** \- 如果 key 不存在，`get()` 返回 `null` ** ** ## 故障排除 ### 问题：写入时出现“429 Too Many Requests” **原因：** 每秒多次写入同一键 **解决方案：** // ❌ 不好 for (令 i = 0; i < 10; i++) { 等待 kv.put('计数器', String(i)); // 速率限制！ } // ✅ 好 - 合并写入常量最终值 = '9'; 等待 kv.put('计数器', FinalValue); // ✅ 好 - 使用带有退避的重试等待 putWithRetry(kv, '计数器', String(i)); ** ** ### 问题：写入后读取过时 **原因：** 最终一致性 - 写入最多需要 60 秒才能在全球范围内传播 **解决方案：** // 接受读取可能在长达 60 秒内过时的情况 // 或者使用持久对象来实现强一致性 // 或者实现应用程序级缓存失效 ** ** ### 问题：“超出操作限制” **原因：** 单次 Worker 调用超过 1000 次 KV 操作 **解决方案：** // ❌ 错误 - 5000 次操作 const keys = Array.from({ length: 5000 }, (_, i) => `key${i}`); for（键的常量键）{ 等待 kv.get(key); // 超过 1000 限制 } // ✅ 好 - 1 次操作（批量读取） const 值 = 等待 kv.get(keys); ** ** ### 问题：列表返回空但光标存在 **原因：** 最近删除/过期的密钥在列表中创建“墓碑” **解决方案：** // 始终检查list_complete，而不是keys.length 让光标：字符串|不明确的; 做{ const result = wait kv.list({ 光标 }); // 即使为空也处理键 processKeys(结果.keys); // 正确：检查 list_complete 光标 = 结果.list_complete ？未定义：结果.光标； while（光标）； ** ** ## 生产清单在部署到生产之前： * 配置了特定于环境的命名空间（“id”与“preview_id”） * 命名空间 ID 存储在环境变量中（不是硬编码） * 为写入实现速率限制重试逻辑 * 为读取设置适当的“cacheTtl”值 * 元数据大小已验证（<1024 字节） * 值大小经过验证 (<25 MiB) * 已验证密钥大小（<512 字节） * 尽可能使用批量操作 * 为 `list()` 正确实现分页 * 空值的错误处理 * 速率限制监控/警报 * 最终一致性行为的文档 ** ** ## 相关文档 * [Cloudflare KV 文档]() * [KV API 参考]() * [KV 限制]() * [KV 的工作原理]() * [Wrangler KV 命令]() ** ** **最后更新**：2025-10-21 **版本**：1.0.0 **维护者**：Jeremy Dawes | [jeremy@jezweb.net]()

Cloudflare Kv

包含技能