HGfast Cloud 灵狐加速 · 一站式全球云网络返回首页

Cloudflare KV是什么?怎么使用:从创建到读写的完整指南

更新于 2026-11-20 · hgfastapp.lol

简答:Cloudflare Workers KV 是面向 Workers 的全球键值存储,适合读多写少的配置、路由和个性化数据。使用时依次创建 KV 命名空间、在 Wrangler 中配置 binding,再通过 env.KV 调用 get、put、delete 和 list;订单状态、强一致计数等场景需改用更合适的存储。

定义:Cloudflare Workers KV 是一种通过键名读取对应值的全球分布式键值存储,重点优化高频读取、低延迟访问和简单数据配置。

先判断:Cloudflare KV适不适合你的数据

如果你需要保存“一个键对应一个值”,并且读取明显多于写入,KV通常是直接的选择。官方文档将配置数据、服务路由元数据和个性化配置列为典型用途;KV通过中心存储与边缘缓存提供全球访问,但不同地点的读取可能存在传播延迟。官方快速入门与工作原理说明均有说明。

  • 适合:功能开关、用户偏好、A/B测试配置、路由元数据、短期令牌、读多写少的缓存型数据。
  • 谨慎使用:需要实时一致的余额、库存、订单状态、并发计数或事务更新。
  • 最快判断:如果业务要求“写入后所有地区立即读到同一个结果”,不要只依赖普通KV。

Cloudflare KV与数据库、缓存有什么区别

KV不是传统关系型数据库,也不只是浏览器缓存。它以键值为主要访问方式,不提供类似SQL数据库的自由查询;同时,它会把读取过的数据缓存到Cloudflare网络中的边缘位置,因此读性能和全球可访问性是重点。

概念主要存储方式适合解决的问题需要注意
Workers KVkey-value键值配置、路由、偏好、读多写少数据最终一致性,不适合依赖原子事务
D1关系型SQL数据库用户资料、商品、订单和关联查询需要按表结构和SQL方式设计
R2对象或文件存储图片、附件、日志、数据集和静态文件不以单个键值的轻量配置读取为主
Durable Objects带状态的协调对象实时协作、WebSocket、全局协调和强一致状态模型和接入方式比KV更复杂

Cloudflare的存储选型文档把KV、D1、R2和Durable Objects分别对应到键值、关系型、对象存储和有状态协调场景,可先按数据类型、查询方式和一致性要求筛选。官方存储产品选型文档

创建KV命名空间:Dashboard与Wrangler两种方法

开始前需要Cloudflare账户、Node.js和一个Workers项目。官方入门流程使用Cloudflare项目创建命令生成Worker,然后创建KV命名空间。命令在本地终端执行,不需要sudo;是否需要额外登录权限取决于你的账户和当前CLI认证状态。

  1. 创建Worker项目:运行npm create cloudflare@latest -- kv-tutorial,按向导选择Worker项目和TypeScript,然后进入目录:cd kv-tutorial。
  2. 用Wrangler创建:运行npx wrangler kv namespace create APP_CONFIG。命令返回namespace ID,保存这个ID。
  3. 用Dashboard创建:进入Workers & Pages相关区域,或进入Workers KV管理页面,选择创建实例,填写命名空间名称后创建。
  4. 核对结果:命名空间名称是便于识别的名称,ID才是绑定配置中指向资源的标识。

如果你使用的是较新的Cloudflare CLI,官方快速入门也提供了cf kv namespaces create --title APP_CONFIG写法。已有项目应优先沿用项目当前使用的CLI,避免把不同命令格式混在一起。创建流程和Wrangler KV命令参考可用于核对当前参数。

配置KV binding:为什么代码里是env.KV

创建命名空间后,Worker代码还不能直接凭名称访问它,必须在Wrangler配置文件中声明KV binding。binding是代码中使用的变量名,id是Cloudflare分配给命名空间的ID;两者可以不同。

在wrangler.jsonc中加入以下配置,把<NAMESPACE_ID>替换成你实际拿到的ID:

{"kv_namespaces":[{"binding":"KV","id":"<NAMESPACE_ID>"}]}

完成后,Worker的fetch(request, env, ctx)函数可以通过env.KV访问这个命名空间。例如,env.KV.get("user:123")中的KV就是配置里的binding名称,不是命名空间显示名称。

binding必须是有效的JavaScript标识符。官方绑定说明还指出,Wrangler本地开发默认使用本地KV;如果希望本地调试连接Cloudflare网络中的远程KV,需要按官方远程绑定方式设置remote选项。KV binding官方说明

一个可复制的Worker示例:GET、PUT、DELETE与LIST

下面示例用URL路径选择操作:GET /item/key读取,PUT /item/key写入请求体,DELETE /item/key删除,GET /list列出键名。它假设配置中已经存在名为KV的binding。

export default { async fetch(request, env) { const url = new URL(request.url); if (url.pathname === "/list" && request.method === "GET") { const result = await env.KV.list(); return Response.json(result); } const match = url.pathname.match(/^\/item\/(.+)$/); if (!match) return new Response("Not Found", { status: 404 }); const key = decodeURIComponent(match[1]); if (request.method === "GET") { const value = await env.KV.get(key); if (value === null) return new Response("Not Found", { status: 404 }); return new Response(value); } if (request.method === "PUT") { const value = await request.text(); await env.KV.put(key, value); return new Response("Saved", { status: 201 }); } if (request.method === "DELETE") { await env.KV.delete(key); return new Response("Deleted"); } return new Response("Method Not Allowed", { status: 405 }); } };

  • 读取:get()找不到键时返回null,不要把空字符串误认为不存在。
  • 写入:put()创建新键或覆盖已有键,建议使用await确认写入Promise完成。
  • 删除:delete()删除指定键,同样需要等待Promise。
  • 列出:list()可配合prefix筛选,例如把用户数据统一命名为user:开头。

对应方法的参数、返回值和限制以读取文档、写入文档、删除文档和列出键文档为准。

TTL与JSON:保存临时数据和结构化配置

KV的值可以保存为字符串、ReadableStream或ArrayBuffer。保存JSON时,需要在写入前调用JSON.stringify(),读取后再调用JSON.parse();KV不会自动把普通字符串变成JavaScript对象。

写入时可以在第三个参数中设置过期时间。例如:

await env.KV.put("session:abc", JSON.stringify({ userId: 123 }), { expirationTtl: 3600 });

expirationTtl表示从现在开始的秒数,官方API文档标注其最小值为60。也可以使用expiration指定Unix时间戳。TTL适合临时会话、短期配置和缓存型数据,但不能替代需要精确生命周期管理的业务数据库。

截至核验时,官方限制页列出普通KV单个值最大25 MiB、键最大512字节、元数据最大1024字节,具体套餐读写额度和其他限制应以账户当前页面为准。官方限制说明

最终一致性:哪些情况会读到旧值

KV写入中心存储后,不会自动同时把新值推送到所有边缘缓存;不同地点的缓存可能仍保留旧值。官方说明称,其他全球位置看到变更可能需要60秒或更久,具体还会受到缓存刷新和cacheTtl设置影响。

  • 配置发布:可以接受短时间内不同地区读到旧版本,但应设计版本号或回滚策略。
  • 计数器:并发写同一个键可能互相覆盖,不能把普通KV当作原子递增存储。
  • 订单与库存:需要事务或强一致读取写入时,应评估D1或Durable Objects。
  • 删除后重建:不存在的键也可能被缓存,因此刚删除或刚创建的键在不同位置的结果可能暂时不一致。

如果你的业务依赖单一协调点、原子操作或事务式读写,官方建议考虑Durable Objects等更适合强一致状态的方案。一致性与缓存机制

本地开发与部署排错:先查binding,再查数据路径

本地运行wrangler dev时,默认使用本地KV。于是你在Dashboard或生产命名空间中已经写入的键,本地读取仍可能得到null;这不一定表示生产数据丢失。

  1. 检查wrangler.jsonc中的binding拼写是否与代码里的env.KV一致。
  2. 检查id是否是目标命名空间的ID,而不是自己填写的名称。
  3. 确认测试命令使用的是本地KV还是远程KV,并避免在生产命名空间写入测试数据。
  4. 在代码中区分“键不存在”和“读取异常”:get()返回null通常是不存在或当前环境没有这条键。
  5. 部署后再次用实际Worker地址测试GET、PUT和DELETE,确认线上binding已经生效。

本地数据与远程数据分离是官方绑定说明明确提到的行为;排查时先确认数据路径,再判断是否是代码或权限问题。本地与远程绑定说明

常见问题

Cloudflare KV是数据库吗?

它可以按键保存和读取数据,官方将其归为键值数据库,但它不等同于支持SQL、关联查询和事务的关系型数据库。需要复杂查询时应评估D1,需要强一致状态时应评估Durable Objects。

为什么代码里的env.KV找不到?

通常是KV binding没有配置、binding名称与代码不一致,或配置中的namespace ID填写错误。检查wrangler.jsonc里的kv_namespaces、binding和id,并确认代码使用的是同一个env属性名。

KV写入后为什么其他地区还读到旧值?

KV使用边缘缓存并采用最终一致性。写入通常先进入中心存储,其他地点的缓存可能需要刷新,因此官方说明变更可能需要60秒或更久才能在其他位置可见。

Cloudflare KV怎么设置过期时间?

调用put时传入第三个参数,例如expirationTtl: 3600表示从写入开始约3600秒后过期。官方API文档标注expirationTtl的最小值为60,临时会话和短期缓存可以使用TTL。

本地wrangler dev为什么读不到Dashboard里的KV数据?

Wrangler本地开发默认使用本地KV,和Cloudflare网络中的远程命名空间不是同一份数据。若要调试远程数据,需要按官方绑定文档配置remote选项,并谨慎避免修改生产数据。

KV能不能做点赞数或库存扣减?

不建议直接把普通KV当作并发计数器或库存事务存储。多个请求同时写同一个键可能互相覆盖;这类需要原子操作或强一致的场景应重新评估数据产品。

相关阅读

参考资料

  1. Cloudflare Workers KV官方快速入门
  2. Cloudflare Workers KV工作原理与一致性说明
  3. Cloudflare KV bindings官方说明
  4. Cloudflare Workers存储产品选型文档
  5. Cloudflare Wrangler KV命令参考
  6. Cloudflare Workers KV限制文档