Cloudflare KV是什么?怎么使用:从创建到读写的完整指南
简答: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 KV | key-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认证状态。
- 创建Worker项目:运行
npm create cloudflare@latest -- kv-tutorial,按向导选择Worker项目和TypeScript,然后进入目录:cd kv-tutorial。 - 用Wrangler创建:运行
npx wrangler kv namespace create APP_CONFIG。命令返回namespace ID,保存这个ID。 - 用Dashboard创建:进入Workers & Pages相关区域,或进入Workers KV管理页面,选择创建实例,填写命名空间名称后创建。
- 核对结果:命名空间名称是便于识别的名称,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;这不一定表示生产数据丢失。
- 检查
wrangler.jsonc中的binding拼写是否与代码里的env.KV一致。 - 检查
id是否是目标命名空间的ID,而不是自己填写的名称。 - 确认测试命令使用的是本地KV还是远程KV,并避免在生产命名空间写入测试数据。
- 在代码中区分“键不存在”和“读取异常”:
get()返回null通常是不存在或当前环境没有这条键。 - 部署后再次用实际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当作并发计数器或库存事务存储。多个请求同时写同一个键可能互相覆盖;这类需要原子操作或强一致的场景应重新评估数据产品。