第14章 KV 键值存储
文档:KV
KV 是一种键值存储,Worker 通过绑定(binding)访问它。每个命名空间对应一个 celld 单元(cell),大于 1 MiB 的值存储在 fleet bucket 中。请参阅 Cloudflare KV 文档 了解 API 细节。
示例
下面的 KV 示例演示了如何在 KV 命名空间中读取、写入和删除值。
index.js
export default {
async fetch(request, env) {
const key = new URL(request.url).pathname.slice(1);
if (!key) return new Response("Use /KEY.", { status: 400 });
if (request.method === "PUT") {
await env.VALUES.put(key, request.body);
return new Response(null, { status: 204 });
}
if (request.method === "DELETE") {
await env.VALUES.delete(key);
return new Response(null, { status: 204 });
}
const value = await env.VALUES.get(key);
return value === null
? new Response("Not found.", { status: 404 })
: new Response(value);
},
};
wrangler.jsonc
{
"name": "kv",
"main": "index.js",
"compatibility_date": "2026-01-01",
"kv_namespaces": [
{
"binding": "VALUES",
"id": "example-values"
}
]
}
API
get(key, type)返回值为 "text"、"json"、"arrayBuffer" 或 "stream"。键不存在时返回 null。getWithMetadata(key, type)除值外还返回写入时的元数据。put(key, value, options)接受字符串、ArrayBuffer、TypedArray 或 ReadableStream。options 包括 expiration(以秒为单位的绝对时间戳)、expirationTtl(从现在起的秒数)以及 metadata。delete(key)删除指定键。list({ prefix, cursor })返回一页键名列表及用于获取下一页的 cursor。
配置与限制
kv_namespaces 配置项包含 binding 和 id。id 是命名空间的标识符,可以是任意字符串,如 Cloudflare 十六进制 ID 或 "sessions"。两个 Worker 若使用相同的 id,则访问同一命名空间。celld 忽略 preview_id。
put() 在写入前会读完 ReadableStream,因此 put(key, request.body) 有效。list() 按字节顺序最多返回 1000 个键,且并发写入不会导致 cursor 跳过键。
celld 遵循 Cloudflare KV 的限制:键最大 512 字节,值最大 25 MiB,元数据最大 1024 字节,单次 bulk get() 最多获取 100 个键。超限调用会失败,celld 不会截断数据。最小过期时间为 60 秒。键在到期时刻立即失效。
每次调用都会路由到拥有该命名空间单元的节点,因此读取开销为一次单元调度。若同一请求多次读取某值,请将其存入局部变量。单个命名空间的写入是串行的,对于计数器等高写入频率的场景,请使用 Durable Object。
写入大于 1 MiB 的值而未配置 fleet bucket 时,会报错:KV large values need a fleet bucket。
与 Cloudflare 的差异
- celld 的读取永远不会返回陈旧值,因为它直达拥有该命名空间的单元。Cloudflare KV 是最终一致性。
- celld 没有边缘缓存。
cacheTtl无效,cacheStatus始终为 null。 - 大于 1 MiB 的值必须配合 fleet bucket 使用。
- 单个命名空间只有一个写入者。如需提升写入容量,请使用多个命名空间。
关于运行时 API 和支持的服务列表,请参阅 Cloudflare 兼容性页面。