# @couchbase/lite-js 中文文档

规范地址：https://npmcn.com/package/%40couchbase/lite-js/

版本：1\.0\.3
npm 元数据更新时间：2026-10-16T08:44:44.325Z
中文译文更新时间：2026-11-10T21:00:48.086Z
软件包许可：See LICENSE\.txt

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

原始 npm 页面：https://www.npmjs.com/package/%40couchbase/lite-js
原文对照：https://npmcn.com/package/%40couchbase/lite-js/?lang=original
项目主页：https://github.com/couchbaselabs/couchbase-lite-js#readme
源码仓库：https://github.com/couchbaselabs/couchbase-lite-js

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

- 包体积（解压后）：8.7 MB，55 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：12 个
- 首次发布：2025-11-11T20:10:39.995Z
- 最新版本发布：2026-10-16T08:44:44.137Z
- 近 30 天下载量：7159（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

这是 Couchbase Lite 的 JavaScript(实际上是 TypeScript) 执行.

## 安装

```sh
npm install @couchbase/lite-js
```

也可以使用：`pnpm add @couchbase/lite-js`、`yarn add @couchbase/lite-js`、`bun add @couchbase/lite-js`

## README

# 用于 JavaScript 的 Couchbase 语句

这是 Couchbase Lite 的 JavaScript(实际上是 TypeScript) 执行.

拟用于网页浏览器.

服务器和CLI环境,如Node.js,Deno和Bun,没有正式支持, 因为它们没有适当执行 [索引数据库](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) API (英语). 在那些环境中你可以使用CBL-JS 帮助 [`fake-indexeddb`](https://www.npmjs.com/package/fake-indexeddb) 软件包, 但是由于数据库没有坚持到磁盘上,所以没有多大用处.

此ReadMe最后一次更新是2025年11月12日.

## 1\. 开始/文件

这个 [维基百科](https://github.com/couchbaselabs/couchbase-lite-js/wiki) 有一些文件介绍 [API 密码](https://glowing-invention-kr285q7.pages.github.io/modules.html),并描述与 其他 Couchbase Lite 平台.

在网页中使用API的例子,请参见 [`examples/browser.ts`](https://npmcn.com/package/%40couchbase/lite-js/examples/browser.ts)。 。 。 . 如果你想自己做这个榜样,你看 ["踢轮胎"](https://github.com/couchbaselabs/couchbase-lite-js/wiki/Kicking-The-Tires)。 。 。 .

### 在您自己的项目中使用

安装国家预防机制软件包 `"@couchbase/lite-js"`。 。 。 .

#### 安装分析( Reo.dev)

此软件包取决于 [`reo-census`](https://www.npmjs.com/package/reo-census),它发送 一次性安装事件 [雷奥德夫](https://reo.dev/) 从其 `postinstall` 剧本. 活动包括软件包名称和版本、OS和Node.js的细节、安装时间戳和 目录、 您的 git 用户名 _域名_ 您的 git 电子邮件地址( 而非完整地址) ,以及 CI环境信息. CBL-JS本身没有分析电话.

选择退出, 设定 `PACKAGE_TRACKER_ANALYTICS=false` 安装时:

```sh
PACKAGE_TRACKER_ANALYTICS=false npm install @couchbase/lite-js
```

不运行依赖关系的安装 安装脚本发送无: `npm install --ignore-scripts`, (中文(简体) ), Bun, pnpm 10+和 Yarn 4 (最后三个跳过依赖) `postinstall` 默认的脚本).

## 2\. 源代码

代码在 `src` 目录. 公共API公布于 `src/couchbase-lite.ts`它只是再出口公共符号.

分目录为:

-   `blip`: 复制机使用的BLIP RPC协议
-   `blob`: Blob/attachment 类和支持代码
-   `database`: 数据库、收集和文件执行;加上公共复制人类
-   `query`: 查询执行情况
-   `replicator`:复制者执行(但不包括其公开的API)
-   `util`: 内部公用事业

测试在源目录中混合, 在命名的文件中 `*.test.ts`。 。 。 .

## 3\. 建设你自己

### 依赖关系

开发需要安装 [阿宝](https://bun.sh/), (中文(简体) ), 或者说 [节点.js](https://nodejs.org/) 财务报告和审定财务报表 [无](https://www.npmjs.com/)。 。 。 . 这些方向假定为包; 如果您使用节点+npm, 则替换 `npm` 页:1 `bun` 在命令行.

软件包依赖性( 将由 Bun 安装) :

-   总论:
    -   [`@logtape/logtape`](https://www.npmjs.com/package/@logtape/logtape) -- 记录
-   英国皇家警察:
    -   [`@foxglove/crc`](https://www.npmjs.com/package/@foxglove/crc) - CRC32核对和.
    -   [`pako`](https://www.npmjs.com/package/pako) - 数据压缩(它是zlib的端口. )
    -   [`isomorphic-ws`](https://www.npmjs.com/package/isomorphic-ws) -- WebSockets(浏览器中不需要)
-   数据库 :
    -   [`dexie`](https://www.npmjs.com/package/dexie) -- IndexedDB高级包装.
    -   [`fake-indexeddb`](https://www.npmjs.com/package/fake-indexeddb) - 模拟索引DB执行(浏览器不需要)
    -   [`sha.js`](https://www.npmjs.com/package/sha.js) —— SHA-1 文摘 (使用而不是JS密码,因为它是同步的
    -   [`buffer`](https://www.npmjs.com/package/buffer) -- 需要使用 `sha.js` 在浏览器中.
-   查询 :
    -   [`ohm-js`](https://www.npmjs.com/package/ohm-js) -- Parser库,用于N1QL/SQL++.
    -   [`date-fns`](https://www.npmjs.com/package/date-fns) - N1QL 日期/时间功能
    -   [`regexp.escape`](https://www.npmjs.com/package/regexp.escape) - 逃避正则表达式字符串。 用于实施类似.

### 大楼

要编译类型脚本代码 `./src` 输入已修改的 JavaScript 文件 `./dist`数字 :

1.  `bun install` _(仅第一次)_
2.  `bun run build`

### 运行测试

测试在命名的文件中 `*.test.ts`它们由维特公司运营.

-   进行基础(非复制)测试: `bun run test`
-   要在浏览器中运行基础测试 : `bun run test:browser`
-   要用数据库加密进行基础测试: `bun run test:encrypted`
-   为了进行复制测试: `bun run test:replicator` 或者说 `bun run test:replicator-encrypted` (首先需要配置同步网关;见src/database/replicator.ts中的说明)
-   要进行N1QL符合性测试: `bun run test:n1ql` 或者说 `bun run test:niql-encrypted` (需要先下载约24MB的测试数据;参见src/query/N1QL TestSite.ts中的取向)

### 集成测试 aka the TDK

> 注:TDK是库克基地的内部,不公开.

所有 Couchbase Lite 平台的集成和系统测试均由 [测试开发套件](https://github.com/couchbaselabs/couchbase-lite-tests) (中文(简体) ). 集成 CBL-JS 的胶水编码在 [`servers/javascript`](https://github.com/couchbaselabs/couchbase-lite-tests/tree/main/servers/javascript) 目录.

## 4\. 运行实例

### ...在网页浏览器中

见维基页面 ["踢轮胎"](https://github.com/couchbaselabs/couchbase-lite-js/wiki/Kicking-The-Tires)。 。 。 .

### ...从命令行

我们有一个在服务器环境中复制的测试(Bun或节点.js). 由于索引DB不可用,它使用 [虚构索引b](https://www.npmjs.com/package/fake-indexeddb) 软件包; 这个数据库是麻黄的,因为它只用于测试目的.

要运行,请先在顶部阅读指令 [`examples/sync_collections_node.ts`](https://npmcn.com/package/%40couchbase/lite-js/examples/sync_collections_node.ts) 并设置您的服务器(同步网关或边缘服务器).

然后运行 `bun run examples/sync_collections_node.ts`

## 常见问题

### @couchbase/lite-js 是什么？

这是 Couchbase Lite 的 JavaScript\(实际上是 TypeScript\) 执行\.

### 如何安装 @couchbase/lite-js？

在项目目录运行 npm install @couchbase/lite-js，或使用 pnpm add / yarn add / bun add。

### @couchbase/lite-js 支持 TypeScript 吗？

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

### @couchbase/lite-js 支持 ESM 还是 CommonJS？

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

### @couchbase/lite-js 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @couchbase/lite-js 可以商用吗？

@couchbase/lite-js 使用 See LICENSE\.txt 许可。声明的许可为 See LICENSE\.txt，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @couchbase/lite-js 的下载量有多少？

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

### @couchbase/lite-js 还在维护吗？

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