# @gristlabs/sqlite3 中文文档

规范地址：https://npmcn.com/package/%40gristlabs/sqlite3/

版本：6\.0\.1-grist\.1
npm 元数据更新时间：2026-06-11T16:32:35.344Z
中文译文更新时间：2026-11-17T01:43:36.937Z
软件包许可：BSD-3-Clause

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

原始 npm 页面：https://www.npmjs.com/package/%40gristlabs/sqlite3
原文对照：https://npmcn.com/package/%40gristlabs/sqlite3/?lang=original
项目主页：https://github.com/gristlabs/node-sqlite3
源码仓库：https://github.com/gristlabs/node-sqlite3

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

- 包体积（解压后）：3.4 MB，25 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.17\.0
- 运行依赖：4 个
- peer 依赖：node-gyp 12\.x
- 首次发布：2019-07-03T05:23:25.180Z
- 最新版本发布：2026-06-11T16:32:35.108Z
- 近 30 天下载量：9960（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 3 个）

## 中文简介

一个同步、非屏蔽的 SQLite3 绑定

## 安装

```sh
npm install @gristlabs/sqlite3
```

也可以使用：`pnpm add @gristlabs/sqlite3`、`yarn add @gristlabs/sqlite3`、`bun add @gristlabs/sqlite3`

## README

# : 不输入: \[DEPECATED\] 节点- sqlite3

**说明:** 此寄存器目前尚未保存 。 我们将不更新其任何问题或撤回请求.

* * *

同步、无阻断 [SQLite 3 请检查url=值 (帮助)](https://sqlite.org/) 约束 [节点.js](http://nodejs.org/)。 。 。 .

[![Latest release](https://img.shields.io/github/release/TryGhost/node-sqlite3.svg)](https://www.npmjs.com/package/sqlite3) ![Build Status](https://github.com/TryGhost/node-sqlite3/workflows/CI/badge.svg?branch=master) [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmapbox%2Fnode-sqlite3.svg?type=shield)](https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmapbox%2Fnode-sqlite3?ref=badge_shield) [![N-API v3 Badge](https://img.shields.io/badge/N--API-v3-green.svg)](https://nodejs.org/dist/latest/docs/api/n-api.html#n_api_n_api) [![N-API v6 Badge](https://img.shields.io/badge/N--API-v6-green.svg)](https://nodejs.org/dist/latest/docs/api/n-api.html#n_api_n_api)

# 特征

-   直向查询和参数绑定接口
-   全部缓冲/ Blob 支持
-   广泛 [调试支持](https://github.com/tryghost/node-sqlite3/wiki/Debugging)
-   [查询序列化](https://github.com/tryghost/node-sqlite3/wiki/Control-Flow) API 密码
-   [扩展支持](https://github.com/TryGhost/node-sqlite3/wiki/API#databaseloadextensionpath-callback),包括捆绑支持 [json1 扩展](https://www.sqlite.org/json1.html)
-   大测试套房
-   以现代 C++ 写并测试内存泄漏
-   Bundles SQLite v3.51.3, 或者可以使用本地的 SQLite 构建

# 安装

你用得着 [`npm`](https://github.com/npm/cli) 或者说 [`yarn`](https://github.com/yarnpkg/yarn) 要安装 `sqlite3`数字 :

-   (建议)最新出版的套装:

```bash
npm install sqlite3
# or
yarn add sqlite3
```

-   GitHub (英语) `master` 分支 : `npm install https://github.com/tryghost/node-sqlite3/tarball/master`

### 预建二进制

`sqlite3` v5+ 被重写为使用 [节点- API](https://nodejs.org/api/n-api.html) 因此,预建的二进制不需要为特定节点版本而构建. `sqlite3` 目前为节点-API v3和v6同时构建. 检查 [节点- API 版本矩阵](https://nodejs.org/api/n-api.html#node-api-version-matrix) 以确保您的节点版本支持其中之一。 预建的二进制应在Node v20.17.0+上支持.

该模块使用 [`prebuild-install`](https://github.com/prebuild/prebuild-install) 以下载您平台的预建二进制,如果存在。 这些二进制在 GitHub Releases 为 `sqlite3` 超过5.0.2的版本,其主机为S3。 目前提供的目标如下:

-   `darwin-arm64`
-   `darwin-x64`
-   `linux-arm64`
-   `linux-x64`
-   `linuxmusl-arm64`
-   `linuxmusl-x64`
-   `win32-x64`

很遗憾, [预建](https://github.com/prebuild/prebuild/issues/174) 无法区分 `armv6` 财务报告和审定财务报表 `armv7`,转而使用 `arm` 作为 `{arch}`。在修复之前,您仍然需要安装 `sqlite3` 从 [来源](https://npmcn.com/package/%40gristlabs/sqlite3/#readme-source-install)。 。 。 .

如果CI支持在其它平台和架构上更上一层楼,未来可能会增加对其他平台和架构的支持.

如果你的环境得不到支持,它就会用到 `node-gyp` 来构建 SQLite,但您需要安装 C++ 编译器和链接器.

### 其他安装方式

也有可能让自己的建筑 `sqlite3` 从源代码取出, 而不是它的 npm 包 ([见下文.](https://npmcn.com/package/%40gristlabs/sqlite3/#readme-source-install)) (中文(简体) ).

这个 `sqlite3` 模块也与 [节点- webkit](https://github.com/rogerwang/node-webkit) 如果节点-webkit包含一个支持的Node.js引擎版本. [(见下文)](https://npmcn.com/package/%40gristlabs/sqlite3/#readme-building-for-node-webkit)

SQLite 的游戏 [SQLCipher 扩展名](https://github.com/sqlcipher/sqlcipher) 也得到支持. [(见下文)](https://npmcn.com/package/%40gristlabs/sqlite3/#readme-building-for-sqlcipher)

# API 密码

见 [API 文档](https://github.com/TryGhost/node-sqlite3/wiki/API) 在维基文库中.

# 使用量

**说明:** 模块必须是 [已安装](https://npmcn.com/package/%40gristlabs/sqlite3/#readme-installing) 在使用前使用.

```js
const sqlite3 = require('sqlite3').verbose();
const db = new sqlite3.Database(':memory:');

db.serialize(() => {
    db.run("CREATE TABLE lorem (info TEXT)");

    const stmt = db.prepare("INSERT INTO lorem VALUES (?)");
    for (let i = 0; i < 10; i++) {
        stmt.run("Ipsum " + i);
    }
    stmt.finalize();

    db.each("SELECT rowid AS id, info FROM lorem", (err, row) => {
        console.log(row.id + ": " + row.info);
    });
});

db.close();
```

## 源安装

跳过搜索预编译的二进制,并从源头强制构建,使用

```bash
npm install --build-from-source
```

Sqlite3模块仅依赖于libsqlite3. 然而,默认情况下,将构建一个内部/捆绑的sqlite副本并静态连接,因此不需要外部安装的sqlite3.

如果你想在外立方块上安装,则需要通过 `--sqlite` 参数到 `npm` 包装 :

```bash
npm install --build-from-source --sqlite=/usr/local
```

如果建筑物相对于外部的 sqlite 3 ,则确保开发标题可用. Mac OS X 的飞船,默认使用这些. 如果你没有安装,就安装 `-dev` 软件包与您的软件包管理器, 例如 . `apt-get install libsqlite3-dev` 为德比安/乌本图. 确定你至少拥有 `libsqlite3` >= 3.6.

注意,如果在OS X上与土生土长安装的 sqlite 相对抗的建筑可以做到:

```bash
npm install --build-from-source --sqlite=/usr/local/opt/sqlite/
```

## 自定义文件头( magic)

默认 sqlite 文件头为"SQLite格式 3". 您可以指定一个不同的魔法, 虽然这将使标准的工具和库无法使用您的文件 .

```bash
npm install --build-from-source --sqlite_magic="MyCustomMagic15"
```

请注意,魔法 _必须_ 字符长为15个(16个字节,包括无效的终止符).

## 节点-webkit大楼

因为ABI的不同, `sqlite3` 必须在习惯中构建,用于 [节点- webkit](https://github.com/rogerwang/node-webkit)。 。 。 .

要建设 `sqlite3` 节点- webkit :

1.  安装 [`nw-gyp`](https://github.com/rogerwang/nw-gyp) 全球: `npm install nw-gyp -g` _(除非已经安装)_
    
2.  以自定义旗标构建模块 `--runtime`, (中文(简体) ), `--target_arch`,以及 `--target`数字 :
    

```bash
NODE_WEBKIT_VERSION="0.8.6" # see latest version at https://github.com/rogerwang/node-webkit#downloads
npm install sqlite3 --build-from-source --runtime=node-webkit --target_arch=ia32 --target=$(NODE_WEBKIT_VERSION)
```

您也可以在内部运行此命令 `sqlite3` 退出 :

```bash
npm install --build-from-source --runtime=node-webkit --target_arch=ia32 --target=$(NODE_WEBKIT_VERSION)
```

请记住:

-   你必须提供权利 `--target_arch` 旗帜. `ia32` 需要瞄准32bit节点-webkit构建,同时 `x64` 将瞄准64bit节点-webkit构建(如果可供您的平台使用).
    
-   之后 `sqlite3` 为节点-webkit所建的软件包不能在vanilla Node.js中运行(反之亦然).
    
    -   譬如说, `npm test` -webkit的软件包将失败.

访问“[使用节点模块](https://github.com/rogerwang/node-webkit/wiki/Using-Node-modules)”节点-webkit的wiki中的文章,以了解更多细节.

## SQLCipher大楼

关于建造SQLCipher的指示,见 [用于节点的 SQLCipher 建筑](https://coolaj86.com/articles/building-sqlcipher-for-node-js-on-raspberry-pi-2/)或者,您可以用本地软件包管理器安装.

要对 SQLCipher 运行, 您需要编译 `sqlite3` 从源代码通过构建选项, 如:

```bash
npm install sqlite3 --build-from-source --sqlite_libname=sqlcipher --sqlite=/usr/

node -e 'require("sqlite3")'
```

如果您的 SQLCipher 安装在一个自定义位置( 如果您自己编译并安装) , 您需要设置一些环境变量 :

### 在OS X与本乡人

设定位置 `brew` 安装它:

```bash
export LDFLAGS="-L`brew --prefix`/opt/sqlcipher/lib"
export CPPFLAGS="-I`brew --prefix`/opt/sqlcipher/include/sqlcipher"
npm install sqlite3 --build-from-source --sqlite_libname=sqlcipher --sqlite=`brew --prefix`

node -e 'require("sqlite3")'
```

### 在大多数Linuxes上(包括Raspberry Pi)

设定位置 `make` 安装它:

```bash
export LDFLAGS="-L/usr/local/lib"
export CPPFLAGS="-I/usr/local/include -I/usr/local/include/sqlcipher"
export CXXFLAGS="$CPPFLAGS"
npm install sqlite3 --build-from-source --sqlite_libname=sqlcipher --sqlite=/usr/local --verbose

node -e 'require("sqlite3")'
```

### 自定义构建与电子

运行 `sqlite3` 结束 [电子重建](https://github.com/electron/electron-rebuild) 不保留 SQLCipher 扩展,所以需要一些额外的旗帜来使这种构建Electron兼容.  `npm install sqlite3 --build-from-source` 命令需要这些额外的旗帜( 确保用您正在工作的当前电子版本替换目标版本 ):

```bash
--runtime=electron --target=18.2.1 --dist-url=https://electronjs.org/headers
```

对于与Homebrew的MacOS,命令应该看起来像如下:

```bash
npm install sqlite3 --build-from-source --sqlite_libname=sqlcipher --sqlite=`brew --prefix` --runtime=electron --target=18.2.1 --dist-url=https://electronjs.org/headers
```

# 测试

```bash
npm test
```

# 贡献者

-   [丹尼尔·洛克尔](https://github.com/daniellockyer)
-   [康斯坦丁·卡费尔](https://github.com/kkaefer)
-   [丹·斯普林迈尔](https://github.com/springmeyer)
-   [威尔怀特](https://github.com/willwhite)
-   [奥兰多·巴斯克兹](https://github.com/orlandov)
-   [阿尔泰姆·库斯蒂科夫](https://github.com/artiz)
-   [埃里克·弗雷德里克森](https://github.com/grumdrig)
-   [约翰·赖特](https://github.com/mrjjwright)
-   [瑞安·达尔](https://github.com/ry)
-   [汤姆·麦克赖特](https://github.com/tmcw)
-   [卡特·塔克斯顿](https://github.com/carter-thaxton)
-   [奥德里乌斯·卡祖卡乌斯卡斯](https://github.com/audriusk)
-   [约翰尼斯·绍尔](https://github.com/pyneo)
-   [密斯高尔](https://github.com/Mithgol)
-   [邱德](https://github.com/kewde)

# 承认

感谢 [奥兰多·巴斯克兹](https://github.com/orlandov), (中文(简体) ), [埃里克·弗雷德里克森](https://github.com/grumdrig) 财务报告和审定财务报表 [瑞安·达尔](https://github.com/ry) 他们的SQLite绑定节点, 和Meraleph 在Freenode的#v8 回答问题.

此模块最初由 [映射框](https://mapbox.com/) 现在由( a) [鬼头](https://ghost.org/)。 。 。 .

# 更改日志

我们用 [GitHub 发布](https://github.com/TryGhost/node-sqlite3/releases) 关于最新版本的说明。 见 [变动情况](https://github.com/TryGhost/node-sqlite3/blob/b05f4594cf8b0de64743561fcd2cfe6f4571754d/CHANGELOG.md) 有关旧版本的详细信息.

# 版权和许可证

版权 (c) 2013-2026 Mapbox & Ghost基金会

`node-sqlite3` 实值 [BSD 许可](https://github.com/tryghost/node-sqlite3/raw/master/LICENSE)。 。 。 .

[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmapbox%2Fnode-sqlite3.svg?type=large)](https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmapbox%2Fnode-sqlite3?ref=badge_large)

## 常见问题

### @gristlabs/sqlite3 是什么？

一个同步、非屏蔽的 SQLite3 绑定

### 如何安装 @gristlabs/sqlite3？

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

### @gristlabs/sqlite3 支持 TypeScript 吗？

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

### @gristlabs/sqlite3 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @gristlabs/sqlite3 需要什么版本的 Node\.js？

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

### @gristlabs/sqlite3 可以商用吗？

@gristlabs/sqlite3 使用 BSD-3-Clause 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。另外不得用原作者名义为衍生产品背书。以上为概括，不构成法律意见，请以许可原文为准。

### @gristlabs/sqlite3 的下载量有多少？

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

### @gristlabs/sqlite3 还在维护吗？

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

