Cloudflare KV 怎么批量读取和列出 key？

我在本地给 KV 的 get 传了一个超过 100 个 key 的数组，直接返回 400。KV 的批量能力有，但有边界，而且读和写不在同一个地方。

批量读用 get 传 key 数组，最多 100 个，返回 Map；批量写不在 Worker 绑定里，要走 Wrangler 的 kv bulk 或 REST API；列 key 用 list，是否结束只能看 list_complete。

这几个入口各有各的细节，计费方式也不同。下面按你会遇到的顺序说。如果你想知道它们为什么不能替代查询，答案在最后一节。

一次怎么读多个 key？

get 传一个 key 数组，返回一个 Map，缺失的 key 对应 null：

const many = await env.CONFIG.get(["a", "b"]);

我在本地确认过：缺失项是 null，一次请求超过 100 个 key 返回 400。单个 key 的 getWithMetadata 返回 { value, metadata }。

批量读在“每次 Worker 调用最多 1,000 次 KV 操作”的上限里只算 1 次，但计费按读取的 key 数。所以批量读省的是调用次数，不是钱，详见 Cloudflare KV 的限额和计费是怎么算的？。

批量写入怎么做？

Worker 绑定里只有单 key 的 put。要批量写，用 Wrangler 的 kv bulk 命令，或者调用 REST API。

list 怎么列出 key？

const page = await env.CONFIG.list({ prefix: "flags:", limit: 100 });

结果按 key 的 UTF-8 字典序排列，用 list_complete 判断是否已经列完。

list 翻页有哪些坑？

官方文档提到两个：

• 空的 keys 数组不代表列完了。 刚过期或刚删除的 key 会被扫描到但不返回，所以一页可能是空的，下一页还有内容。要看 list_complete，不要看数组长度。
• 带 prefix 分页时，每次调用都要重复传同一个 prefix。

能用 list 做业务查询吗？

不要。list 只是按前缀列 key，会受最终一致和过期 key 扫描的影响，不是查询。需要查询、排序、关联时，用 D1。如果你只是想按已知 key 取值，直接 get，别先 list。KV 为什么读到的可能是旧值，见 Cloudflare KV 能当数据库用吗？。

限额与行为以 2026-10 官方文档为准，会变化。批量读只算 1 次调用但按 key 数计费、批量写入走 Wrangler 或 REST、list 的空 keys 数组与重复传 prefix，都是官方文档的说法，我没有本地验证。缺失 key 返回 null、批量读返回 Map、超过 100 个 key 返回 400、getWithMetadata 的返回形状，我在本地 wrangler dev 上跑过；list 的行为我没有在本地跑。