进阶 celld.dev 2026-10-11 10:08:47 · 36 阅读

第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 兼容性页面。

本篇用到的工具

评论 (0)