# @deno/kv 中文文档

规范地址：https://npmcn.com/package/%40deno/kv/

版本：0\.14\.0
npm 元数据更新时间：2026-06-06T09:18:57.209Z
中文译文更新时间：2026-11-11T22:40:48.958Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40deno/kv
原文对照：https://npmcn.com/package/%40deno/kv/?lang=original
项目主页：https://github.com/denoland/denokv/tree/main/npm
源码仓库：https://github.com/denoland/denokv

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：619 kB，247 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2023-12-05T20:32:45.089Z
- 最新版本发布：2026-06-06T09:18:56.856Z
- 近 30 天下载量：32696（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 2 个）

## 中文简介

一个Deno KV客户端库为Node.js进行了优化.

## 安装

```sh
npm install @deno/kv
```

也可以使用：`pnpm add @deno/kv`、`yarn add @deno/kv`、`bun add @deno/kv`

## README

# `@deno/kv`

![https://github.com/denoland/denokv/actions](https://github.com/denoland/denokv/workflows/npm/badge.svg)

A 类 [德诺 KV](https://deno.com/kv) 为Node.js优化了客户端库.

-   访问 [Deno 部署](https://deno.com/deploy) 远程数据库(或任何) 执行打开的结束点 [KV 连接](https://github.com/denoland/denokv/blob/main/proto/kv-connect.md) (原始内容存档于2019-09-25). Protocol). on Node 18+.
-   创建本地 KV 数据库 [SQL 点](https://www.sqlite.org/index.html),使用优化本地 [国家行动计划](https://nodejs.org/docs/latest-v18.x/api/n-api.html) 软件包 节点 - 兼容由德诺自己创建的数据库.
-   创建由 SQLite 内存文件或由 SQLite 内存文件支持的 ephemory KV 实例 轻量级JS只用于测试.
-   0 JS 依赖性, SQLite 后端的架构特有本地代码 (见下文).
-   简单地调用导出 `openKv` 函数( 返回到 [`Deno.openKv`](https://deno.land/api?s=Deno.openKv&unstable)带有url或 启动本地路径 !

### 快速启动 - 节点 18+

_安装 [npm 软件包](https://www.npmjs.com/package/@deno/kv)_ 👉 `npm install @deno/kv`

_远程 KV 数据库_

```js
import { openKv } from "@deno/kv";

// to open a database connection to an existing Deno Deploy KV database,
// first obtain the database ID from your project dashboard:
// https://dash.deno.com/projects/YOUR_PROJECT/kv

// connect to the remote database
const kv = await openKv(
  "https://api.deno.com/databases/YOUR_DATABASE_ID/connect",
);
// access token for auth is the value of environment variable DENO_KV_ACCESS_TOKEN by default

// do anything using the KV api: https://deno.land/api?s=Deno.Kv&unstable
const result = await kv.set(["from-client"], "hello!");
console.log(result);

// close the database connection
kv.close();

// to provide an explicit access token, pass it as an additional option
const kv2 = await openKv(
  "https://api.deno.com/databases/YOUR_DATABASE_ID/connect",
  { accessToken: mySecretAccessToken },
);
```

_本地 KV 数据库_

```js
import { openKv } from "@deno/kv";

// create a local KV database instance backed by SQLite
const kv = await openKv("kv.db");

// do anything using the KV api: https://deno.land/api?s=Deno.Kv&unstable
const result = await kv.set(["from-client"], "hello!");
console.log(result);

// close the database connection
kv.close();
```

_In- Memory KV 数据库( 无本地代码)_

```js
import { openKv } from "@deno/kv";

// create an ephemeral KV instance for testing
const kv = await openKv("");

// do anything using the KV api: https://deno.land/api?s=Deno.Kv&unstable
const result = await kv.set(["from-client"], "hello!");
console.log(result);

// close the database connection
kv.close();
```

> 实例使用无害环境管理语法,但本软件包支持CJS `require`\- 基于用途 还有

### 本地 KV 数据库

本地磁盘数据库由 [SQL 点](https://www.sqlite.org/index.html),并与创建的数据库兼容 与德诺本身:

-   共享 Rust 代码 [德诺兰/德诺克夫](https://github.com/denoland/denokv) 带着一小口香糖 为节点的本地界面编译 [国家空间局](https://napi.rs/) 框架
-   选择并安装了针对架构的本地软件包依赖性 时间 `npm install` 时间通过标准 npm [同侪依赖机制](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#peerdependencies)

支持下列本土建筑: 建筑主题 建筑主题 建筑主题

|  | 节点18 | 节点20 |
| --- | --- | --- |
| 视窗 x64 | ✓ | ✓ |
| macOS x64 | ✓ | ✓ |
| 马可斯臂64 | ✓ | ✓ |
| Linux x64克努语 | ✓ | ✓ |

### 贷项

-   生成的 Protobuf 代码 [页:1](https://deno.land/x/pbkit/cli/pb/README.md)
-   npm 软件包生成方式 [点](https://github.com/denoland/dnt)
-   初始代码由 [天平/kv-连接基特](https://github.com/skymethod/kv-connect-kit)

* * *

### API 密码

此套件输出一个单一的便利功能 `openKv`,选择 字符串 `path`,可选 `opts`。取决于 `path` 提供,其中一个 采用了三种不同的执行方式:

-   若为 `path` 被省略或空白,一个瞬间 `in-memory` db 执行 用于测试
-   若为 `path` 是 https 或 https url,则 `remote` 使用客户端执行 连接到 [Deno 部署](https://deno.com/deploy) 或自办 [德诺克夫](https://github.com/denoland/denokv) 实例
-   否则 `path` 被传给当地人 `sqlite` 执行 - 可 指定本地路径或 `:memory:` 用于 SQLite 的 [模拟模式](https://www.sqlite.org/inmemorydb.html)

您可以通过 `implementation` 选项 :

```js
const kv = await openKv("https://example.com/not-really-remote", {
  implementation: "in-memory",
});
```

通过 `debug` 选项到 `console.log` 额外的调试信息 :

```js
const kv = await openKv("http://localhost:4512/", { 
  debug: true
});
```

### 支持的特性

| 特性 | 块状 | 记忆 | 远程( KV 连接) |
| --- | --- | --- | --- |
| `get` 编号 : `getMany` 编号 : `set` 编号 : `delete` 编号 : `list` | ✅ | ✅ | ✅ |
| `atomic()` (检查, `sum` 编号 : `min` 编号 : `max`(中文(简体) ) | ✅ | ✅ | ✅ |
| 密钥过期( O)`expireIn`(中文(简体) ) | ✅ | ✅ | ✅ |
| `watch` | ✅ | ✅ | ✅ |
| `enqueue` 编号 : `listenQueue` | ✅ | ✅ | ❌ |

队列操作不是 KV 连接协议的一部分, 所以它们是 仅可使用本地(sqlite或in-memory)数据库.

### 后端特定选项

每次执行都支持不同的额外选择, 通过第二个参数 `openKv`数字 :

**远程后端**

```ts
export interface RemoteServiceOptions {
  /** Access token used to authenticate to the remote service */
  readonly accessToken: string;

  /** Wrap unsupported V8 payloads to instances of UnknownV8 instead of failing.
   *
   * Only applicable when using the default serializer. */
  readonly wrapUnknownValues?: boolean;

  /** Enable some console logging */
  readonly debug?: boolean;

  /** Custom serializer to use when serializing v8-encoded KV values.
   *
   * When you are running on Node 18+, pass the 'serialize' function in Node's 'v8' module. */
  readonly encodeV8?: EncodeV8;

  /** Custom deserializer to use when deserializing v8-encoded KV values.
   *
   * When you are running on Node 18+, pass the 'deserialize' function in Node's 'v8' module. */
  readonly decodeV8?: DecodeV8;

  /** Custom fetcher to use for the underlying http calls.
   *
   * Defaults to global 'fetch'`
   */
  readonly fetcher?: Fetcher;

  /** Max number of times to attempt to retry certain fetch errors (like 5xx) */
  readonly maxRetries?: number;

  /** Limit to specific KV Connect protocol versions */
  readonly supportedVersions?: KvConnectProtocolVersion[];
}
```

**原生 SQLite 后端**

```ts
export interface NapiBasedServiceOptions {
  /** Enable some console logging */
  readonly debug?: boolean;

  /** Underlying native napi interface */
  readonly napi?: NapiInterface;

  /** Custom serializer to use when serializing v8-encoded KV values.
   *
   * When you are running on Node 18+, pass the 'serialize' function in Node's 'v8' module. */
  readonly encodeV8: EncodeV8;

  /** Custom deserializer to use when deserializing v8-encoded KV values.
   *
   * When you are running on Node 18+, pass the 'deserialize' function in Node's 'v8' module. */
  readonly decodeV8: DecodeV8;

  /** The database will be opened as an in-memory database. */
  readonly inMemory?: boolean;
}
```

**轻量级记忆后端**

```ts
export interface InMemoryServiceOptions {
  /** Enable some console logging */
  readonly debug?: boolean;

  /** Maximum number of attempts to deliver a failing queue message before giving up. Defaults to 10. */
  readonly maxQueueAttempts?: number;
}
```

### 其他运行时间

此套件针对Node.js,但可能在其他运行时间起作用,但有以下的警告: 1

**V8 序列化**

德诺 KV 使用 [V8 请检查URL=值 (帮助)](https://v8.dev/docs)序列化格式,用于序列化值, 由 Deno 本地提供, 当使用此格式时 自动通过节点上的软件包 [内置 `v8` 模块](https://nodejs.org/api/v8.html#serialization-api)。 。 。 .

[阿宝](https://bun.sh/) 还提供a `v8` 模块,但在引擎盖下使用不同的序列化格式(JavaScriptCore).

如果您想要使用Deno部署数据库或其他共享数据库, 数据腐败问题可能会出现 使用实际 V8 序列化的节点/Deno : 您可以创建无法读取的数据, 或者反之亦然.

为此, `openKV` 在 Bun 上默认会丢弃,以避免出乎意料的数据腐败.

如果您只读取并写入您在 Bun 的本地数据库, 您可以通过提供 习惯 `encodeV8`, (中文(简体) ), `decodeV8` 明确作为第二个参数 `openKv`。注意任何数据都无法读取 节点(使用@deno/kv),或Deno - 因为他们使用实际的V8格式.

```js
import { openKv } from "@deno/kv";
import { serialize as encodeV8, deserialize as decodeV8 } from "v8"; // actually JavaScriptCore format on Bun!

const kv = await openKv("kv.db", { encodeV8, decodeV8 });
```

如果当地人 `v8` 模块在运行时间上不可用,您可以使用此软件包提供的基于JS的有限V8序列器. 它只支持数量有限的值类型(`string`, (中文(简体) ), `boolean`, (中文(简体) ), `null`, (中文(简体) ), `undefined`,因此考虑使用 `JSON.parse`编号 :`JSON.stringify` ,用于存储的字符串.

```js
import { openKv, makeLimitedV8Serializer } from "@deno/kv";

const { encodeV8, decodeV8 } = makeLimitedV8Serializer();

const kv = await openKv("kv.db", { encodeV8, decodeV8 });
```

V8 序列化仅对 SQLite 和远程数据库, 内存执行是必要的 调用时使用 `openKv()` 或者说 `openKv('')` 使用进程内值和 [结构化](https://developer.mozilla.org/en-US/docs/Web/API/structuredClone) 换句话说.

## 常见问题

### @deno/kv 是什么？

一个Deno KV客户端库为Node\.js进行了优化\.

### 如何安装 @deno/kv？

在项目目录运行 npm install @deno/kv，或使用 pnpm add / yarn add / bun add。

### @deno/kv 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @deno/kv 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @deno/kv 可以商用吗？

@deno/kv 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @deno/kv 的下载量有多少？

根据 npm 官方下载统计，@deno/kv 在 2026/10/12 – 2026/11/10 这 30 天内被下载 32,696 次，日均约 1,090 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @deno/kv 还在维护吗？

最新版本 0\.14\.0 发布于 2026/06/06（5 个月前）；至今共发布 14 个版本，其中过去 12 个月发布了 2 个；首次发布于 2023/12/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。