文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>边缘安全加速平台 EO>Pages>存储>KV

KV

最近更新时间：2026-05-21 16:03:42

我的收藏

本页目录：

概述

EdgeOne Pages KV 是多边缘节点部署的键值持久化存储，遵循最终一致性（边缘节点缓存最长 60s），适合存储配置、计数器、Session 等小型数据。
注意：
免费版套餐下单账户存储容量为 1GB。
当前仅支持在 Edge Functions 中使用。

工作原理

KV 采用中心化存储 + 边缘缓存架构，遵循最终一致性：写入会并行落到当前最近边缘节点和中心存储；读取时优先走最近边缘节点的本地缓存，缓存未命中或已过期时（最长 60 秒）回中心存储拉取并刷新缓存。
操作
行为
写入
并行写入当前最近边缘节点和中心存储；写入完成后，同一节点立即可读到最新值。
读取
优先命中最近边缘节点的缓存（毫秒级响应）；缓存未命中或已过期时，回中心存储拉取最新值并刷新缓存。
更新 / 删除
当前节点立即生效；其他边缘节点的旧缓存最长 60 秒内自然过期，过期后即可读到最新值。
注意：
写入操作只更新发起请求的节点缓存，其他节点仍可能在最长 60 秒内读到旧值。如果业务需要全局立即一致，请使用 Blob 存储 的强一致模式。

使用场景

计数器

您可以根据业务需求，将某个按钮、页面的点击数存储到 KV，点击时更新 KV 中的键值记录，以便统计和分析点击或访问行为。

密钥库

对于一些敏感性的信息，不方便放置在代码仓库中时，您可以将其存储到 KV 中，动态获取以便更好地保护您的数据。

购物车

KV 可以跨多个页面、多个终端地保留用户数据，可以助您便捷实现用户购物车、用户订单等简单的业务需求。

基础概念

账户

KV 账户是 Pages 业务中 KV 用量统计和计费的最小单位。一个 Pages 账户对应一个 KV 账户，用户在控制台页面开通后创建。账户存储容量 1GB。

命名空间

命名空间（namespace）是 KV 中数据隔离的基本单位。每个命名空间可以看作是一个独立的 database，各个命名空间之间的数据互不干扰。一个账户可以创建 10 个命名空间。

键值对

键值对是一种用户存储数据的结构，其中每个数据项由两个部分组成：键（Key）和值（Value）。键是唯一的标识符，用于标识值，值是与键相关联的数据。

变量名

变量名是绑定项目跟命名空间时定义的运行时环境变量名称。在使用命名空间数据之前，需要先将命名空间跟 Pages 项目进行绑定。命名空间跟项目的绑定关系为多对多，在绑定时通过不同的运行时环境变量名称来区分使用。

快速开始

初始化账户

1. 进入 控制台，切换到 pages > 存储 > KV 存储页面。
2. 申请开通账户：单击立即申请。




创建命名空间

1. 进入命名空间列表：开通 KV 账户后，在“KV 存储”页面，单击创建命名空间。



2. 创建命名空间：输入需要创建的命名空间名称后，单击创建，等待创建完成。



3. 创建完成：创建完成后，可以在命名空间列表页，查看创建好的命名空间。




添加记录

1. 进入命名空间详情：在命名空间列表中，点击对应命名空间名称，进入命名空间详情。



2. 添加记录：单击新建记录。



3. 创建完成：创建完成后，可以在记录列表中查看添加好的记录。




绑定命名空间

命名空间与项目间的绑定，在“项目”和“KV 存储”中，都可以进行绑定。
KV 存储中绑定
1. 进入关联项目：在命名空间详情页，单击关联项目选项卡。



2. 绑定项目：单击绑定项目。



3. 绑定成功：绑定成功后，在绑定项目列表可以查看绑定好的项目。



项目中绑定
1. 进入项目- KV 存储：进入项目详情后，单击 KV 存储菜单。



2. 绑定命名空间：单击绑定命名空间。



3. 绑定成功：绑定成功后，在绑定命名空间列表可以查看绑定好的命名空间。




API

说明：
以下示例的 my_kv 是您绑定项目跟命名空间时的变量名。
目前提供了一组 KV 存储操作方法供 Pages Functions 使用，具体方法如下：

put

写入 KV 数据，用户创建新的键值对或者更新已有键值对的值。
put(key: string,value: string | ArrayBuffer | ArrayBufferView | ReadableStream): Promise<void>;
参数
key：需要创建或更新的键，长度小于等于 512 B，仅支持数字、字母及下划线。
value：需要写入的数据，数据长度小于等于 25 MB。
返回值
返回一个 Promise，需要 await 该 Promise 以验证写入是否成功。
使用示例
await my_kv.put(key, value);

get

根据特定的 key 读取 KV 中的数据，并根据指定类型返回数据。
get(key:string, object?:{type:string}): Promise<value:string|object|ArrayBuffer|ReadableStream>
参数
key：指定获取数据的 key。
type：用于指定返回的 value 类型，默认为 text。
text：String，将 value 转成 string 的形式返回。
json：Object，用户将 json 反序列化为 object 形式返回。
arrayBuffer：ArrayBuffer，用户将二进制的 value 转换为 ArrayBuffer 返回。
stream：ReadableStream，通常用于 value 较大的场景。
返回值
返回一个 Promise，需要 await 该 Promise 以获取 value。如果 key 不存在或 value 为空时，则返回 null。
使用示例
let value = await my_kv.get(key);
let value = await my_kv.get(key, "json");
let value = await my_kv.get(key, {type: "json"});

delete

从 KV 中删除指定的 key。
delete(key: string): Promise<void>;
参数
key：需要删除的键值对的 key。
返回值
返回一个 Promise，需要 await 该 Promise 以验证删除是否成功。
使用示例
await my_kv.delete(key);

list

用于遍历 KV 中的所有 key。
list({prefix?: string, limit?: number, cursor?: string}): Promise<ListResult>;
参数
prefix：用于过滤指定前缀的键。默认为空时，按照字典序排序返回。
limit：返回的 key 的最大数量，用于分页。默认值为 256，上限为 256。
cursor：游标，从指定键开始遍历，用于分页。默认为空。
返回值
返回一个 Promise，需要 await 该 Promise 以获取 ListResult：
class ListResult {
    complete: Boolean;
    cursor: String;
    keys: Array<ListKey>;
}

class ListKey {
    key: String;
}
complete：标记 list 操作是否完成，true 完成，false 未完成。
cursor：游标，为下一页的第一个 key，当 list 遍历完成时为 null。
keys：描述每个 key 的 object 数组。
使用示例
// 通过 list 获取部分数据
let result = await kv.list({ "prefix": "a", "limit": 10, "cursor": "abc" });

// 通过 list 遍历所有数据
let result;
let cursor;
do {
    result = await kv.list(options);
    cursor = result.cursor;
} while (result && !result.complete);

示例

export async function onRequest({ request, params, env }) {
    // 获取变量名为 my_kv 的命名空间 key
    let count = await my_kv.get("count");
    count = Number(count) + 1;
    
    // 重新写入 visitCount 键值
    await my_kv.put("count", String(count));

    return new Response("ok", {});
}

示例模板

使用 KV 记录页面访问数：
中国站