# @dao-xyz/sqlite3-vec 中文文档

规范地址：https://npmcn.com/package/%40dao-xyz/sqlite3-vec/

版本：0\.0\.19
npm 元数据更新时间：2025-09-08T15:02:03.598Z
中文译文更新时间：2026-11-11T11:18:36.140Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：12.6 MB，45 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2025-09-07T08:06:49.130Z
- 最新版本发布：2025-09-08T15:02:03.392Z
- 近 30 天下载量：2288（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 0 个）

## 中文简介

统一 SQLite + sqlite-vec 跨越浏览器(Wasm)和节点(native).

## 安装

```sh
npm install @dao-xyz/sqlite3-vec
```

也可以使用：`pnpm add @dao-xyz/sqlite3-vec`、`yarn add @dao-xyz/sqlite3-vec`、`bun add @dao-xyz/sqlite3-vec`

## README

# @dao-xyz/sqlite3-vec (英语)

统一 SQLite + sqlite-vec (vec0) 两种浏览器和Node.js.

-   浏览器使用官方的 SQLite Wasm 构建(有 sqlite-vec)——没有设置.
-   节点使用更好的sqlite3(XQ12)并自动加载一个预建的sqlite-vec扩展名 当可用时.
-   两者都有一个导入: `import { createDatabase } from '@dao-xyz/sqlite3-vec'`。 。 。 .

## 快速类型脚本示例(浏览器和节点中的工作)

```ts
// src/app.ts
import { createDatabase } from '@dao-xyz/sqlite3-vec';

// Pick options per environment (optional)
const isBrowser = typeof window !== 'undefined';
const options = isBrowser
  ? { directory: '/myapp' } // Browser (OPFS when available, otherwise in-memory)
  : {}; // Node (native via better-sqlite3)

const db = await createDatabase(options);
await db.open();

// Confirm sqlite-vec is available
const vStmt = await db.prepare('select vec_version() as v');
const vRow = vStmt.get?.({});
console.log('sqlite-vec', vRow?.v);

// Create a small vec0 table and query
await db.exec(
  'CREATE VIRTUAL TABLE IF NOT EXISTS v USING vec0(vector float[3])',
);
const toVec = () =>
  new Float32Array([Math.random(), Math.random(), Math.random()]);

const ins = await db.prepare('INSERT INTO v(rowid,vector) VALUES(?1,?2)');
for (let i = 1; i <= 3; i++) ins.run([i, toVec().buffer]);

const probe = toVec();
const q = await db.prepare(
  'SELECT rowid, vec_distance_l2(vector, ?1) AS d FROM v ORDER BY d LIMIT 2',
);
console.log('Top-2:', q.all([probe.buffer]));

await db.close();
```

注释:

-   在浏览器中, `directory` 在可用时启用 OPFS 备份存储( 落地) 回到记忆中.
-   在节点中,不需要选项. 软件包自动装入本地 sqlite-vec 如果存在扩展名.

## 安装

```bash
npm install @dao-xyz/sqlite3-vec
# optional (for local E2E)
npx playwright install --with-deps chromium
```

## 脚本

-   构建 : `npm run build`
-   演示词:
    -   浏览器 : `npm start` - 打开 `http://127.0.0.1:4321/demo/index.html`
    -   节点( 瓦斯姆/ 记忆中): `npm run start:node`
    -   节点( 本地) : `npm run start:node:native`
-   测试 :
    -   节点 : `npm run test:node`
    -   浏览器 (Playwright) : `npm run test:e2e`

### 项目结构

-   `src/`:用于统一和本土节点条目的源模块.
-   根号 `unified.mjs`, (中文(简体) ), `native.mjs`, (中文(简体) ), `node.mjs`: 从 `src/`。 。 。 .
-   `index.mjs`: 无害环境管理的入站电线接通上层sqlite-wasm有效载荷.
-   `wasm.mjs`: 演示/测试所使用的本地桥; 已公布的镜像 `/wasm` 子路径.
-   `sqlite-wasm/jswasm/`: 上游原子弹有效载荷文件(.mjs/.wasm).

### 类型脚本

-   这包货船满了 `.d.ts` 所有入境点的申报.
-   有条件出口的图示 `.d.ts` 环境:
    -   根:浏览器 `dist/unified-browser.js`,节点 + `dist/unified-node.js`, (中文(简体) ), 类型 • `dist/unified.d.ts`。 。 。 .
    -   子路径 : `./unified`, (中文(简体) ), `./native`,以及 `./wasm` 与联署材料匹配的每个点 财务报告和审定财务报表 `.d.ts`。 。 。 .
-   您不需要额外的配置; 编辑器自动拾取类型 .

### 常见陷阱

-   COOP/COEP信头:需要浏览器 `Cross-Origin-Opener-Policy: same-origin` 财务报告和审定财务报表 `Cross-Origin-Embedder-Policy: require-corp` 装入瓦姆 共享箭头缓冲器(由OPFS SAH 池使用). 使用所提供的服务器 (单位:千美元)`npm run start:dev`)或配置您的服务器.
-   MIME 类型: 确保 `.mjs` 作为 `application/javascript` 财务报告和审定财务报表 `.wasm` 作为 `application/wasm`。提供的测试服务器处理此操作.
-   OPFS的可用性:一些浏览器/环境(例如:交叉发源地iframes, 不安全起源)屏蔽了OPFS. 统一的API回到记忆中 OPFS无法使用.
-   工人: 如果浏览器缺少模块工人支持,演示加载 a 混合填充剂。 在你的应用程序中,检查模块工人的支持 如果你依赖工人.
-   Bundlers:与Vite一起,将这个包件排除在预捆绑之外,并设置COOP/COEP 页: 1 其他捆绑商可能需要等同的配置.

## 快例 (浏览器, 主线程)

服务文件时需要COOP/COEP头.

```js
// main.js
import sqlite3InitModule from '@dao-xyz/sqlite3-vec/wasm';

const sqlite3 = await sqlite3InitModule({
  print: console.log,
  printErr: console.error,
});
const db = new sqlite3.oo1.DB('/vec.sqlite3', 'ct');

// Confirm sqlite-vec is present
const s = db.prepare('select vec_version() as v');
s.step();
console.log('sqlite-vec', s.get({}).v);
s.finalize();

// Create table and run a tiny vector query
db.exec('CREATE VIRTUAL TABLE v USING vec0(vector float[3])');
const toVec = () =>
  Uint8Array.from({ length: 3 }, () => Math.floor(Math.random() * 256));
const ins = db.prepare('INSERT INTO v(rowid,vector) VALUES(?1,?2)');
for (let i = 1; i <= 4; i++) ins.bind({ 1: i, 2: toVec().buffer }).stepReset();
ins.finalize();

const probe = toVec();
const q = db.prepare(
  'SELECT rowid, vec_distance_l2(vector, ?1) AS d FROM v ORDER BY d LIMIT 2',
);
q.bind({ 1: probe.buffer });
while (q.step()) console.log(q.get());
q.finalize();
db.close();
```

## 统一 API( 浏览器和节点中的工作)

使用选择正确运行时间的单一工厂:

```js
import { createDatabase } from '@dao-xyz/sqlite3-vec';

// Auto: browser -> wasm; Node -> better-sqlite3 if available, else wasm
const db = await createDatabase({ mode: 'auto', directory: '/my/app' });

await db.open();
await db.exec('CREATE VIRTUAL TABLE v USING vec0(vector float[3])');
const stmt = await db.prepare('INSERT INTO v(rowid,vector) VALUES(?1,?2)');
const toVec = () =>
  new Float32Array([Math.random(), Math.random(), Math.random()]);
for (let i = 1; i <= 3; i++) stmt.run([i, toVec().buffer]);

const probe = toVec();
const q = await db.prepare(
  'SELECT rowid, vec_distance_l2(vector, ?1) AS d FROM v ORDER BY d LIMIT 2',
);
console.log(q.all([probe.buffer]));
await db.close();
```

节点快例( 按包名导入, vec0) :

```js
// node.mjs (ESM)
import {
  createDatabase,
  resolveNativeExtensionPath,
} from '@dao-xyz/sqlite3-vec';

const db = await createDatabase({
  /* optionally: loadExtension: '/abs/path/sqlite-vec-<triple>.<ext>' */
});
await db.open();
console.log('native ext:', resolveNativeExtensionPath() || '(none)');

// vec0 table
await db.exec(
  'CREATE VIRTUAL TABLE IF NOT EXISTS v USING vec0(vector float[3])',
);
const toVec = () =>
  new Float32Array([Math.random(), Math.random(), Math.random()]);
const ins = await db.prepare('INSERT INTO v(rowid,vector) VALUES(?1,?2)');
for (let i = 1; i <= 4; i++) ins.run([i, toVec().buffer]);

const probe = toVec();
const q = await db.prepare(
  'SELECT rowid, vec_distance_l2(vector, ?1) AS d FROM v ORDER BY d LIMIT 2',
);
console.log('top-2:', q.all([probe.buffer]));
await db.close();
```

选项 :

-   `mode`数字 : `'auto' | 'native' | 'wasm'` (默认) `'auto'`) (中文(简体) ).
-   `directory`:持续位置. 在浏览器中,可用时使用OPFS; 否则就回到记忆中 在节点原生地,指向文件路径 节点被忽略了.
-   `extensionPath` (仅节点本地化): sqlite-vec 可加载扩展路径 二进制( 可选) .

## 捐款

见 `DEVS.md` 详细开发、建造、测试和发布说明.

### 运行演示

使用 COOP/COEP 头或 包含微小服务器或您自己的服务器 :

```bash
# simple COOP/COEP server (recommended)
npm run start:dev
# then open http://127.0.0.1:4321/demo/index.html

# or use http-server (requires a build that your browser allows)
npm start
```

## 错误报告

> \[! 警告\]
> 
> 此工程将包含 [SQLite 瓦斯](https://sqlite.org/wasm/doc/trunk/index.md) 与 _没有_ 变化, 除已添加类型脚本外。 请吧 _没有_ 文件问题或特性 关于这里的SQLite Wasm密码的请求。 相反,请 跟着 [SQLite 错误归档指令](https://www.sqlite.org/src/wiki?name=Bug+Reports)。 。 。 . 归档类型Script类型的相关问题和功能请求是好的.

## 节点.js 支持

> \[! 警告\]
> 
> 节点.js支持两种模式:
> 
> -   通过更好的sqlite3(建议;支持持久性)实现原生. 提供 路径到 sqlite-vec 可加载扩展.
> -   瓦斯姆(仅存于记忆;没有持久性).

### 预建二进制( 建议)

安装时, 软件包试图下载一个预建的 sqlite- vec 可装入 用于您的平台的扩展并放在下面 `./dist/native/`。这个镜像 更好的sqlite3使用的方法,在节点上提供了"公正的工作"经验.

-   支持的三进制 :
    -   马可斯: `darwin-x64`, (中文(简体) ), `darwin-arm64`
    -   窗口 : `win32-x64`, (中文(简体) ), `win32-arm64`
    -   Linux glibc : (中文(简体) ) `linux-x64-gnu`, (中文(简体) ), `linux-arm64-gnu`
    -   Linux musl (阿尔卑斯山): `linux-x64-musl`, (中文(简体) ), `linux-arm64-musl`, (中文(简体) ), `linux-armv7-musl`

控件 :

-   `SQLITE3_VEC_PREBUILT=0` ——禁用预建下载(如离线CI).
-   `SQLITE3_VEC_POSTINSTALL=1 SQLITE_VEC_DIR=../sqlite-vec` ——倒计时:建设 安装时来自本地来源.

跑步时, `initNative()` 如果您不这样做, 将自动发现已下载的二进制 通过 `loadExtension` 当然.

在节点中也可以按程序解决检测到的路径 :

```js
import { resolveNativeExtensionPath } from '@dao-xyz/sqlite3-vec';
console.log('Resolved sqlite-vec extension:', resolveNativeExtensionPath());
```

调试 :

-   设定 `SQLITE3_VEC_DEBUG=1` 以登录在 `initNative()`。 。 。 .

决议细节:

-   相对于安装的软件包, 本地扩展是自动发现的 `dist/native/` 目录( 不是应用程序的 cwd ) 。 你可以通过路过来覆盖 `loadExtension` 改为 `createDatabase({ loadExtension })`。 。 。 .

可选:安装时自动本地建置( opt- in)

```bash
# If you want the sqlite-vec native extension built automatically during npm install:
# 1) Ensure you have a local sqlite-vec checkout
# 2) Opt-in via env var and point to the repo
SQLITE3_VEC_POSTINSTALL=1 SQLITE_VEC_DIR=../sqlite-vec npm install

# Postinstall will attempt to run scripts/build-sqlite-vec.sh and place the
# resulting binary under ./dist/native/.
```

### 节点演示

```bash
# Wasm (in-memory)
npm run start:node

# Native (better-sqlite3); uses $SQLITE_VEC_EXT if provided, otherwise tries ./dist/native
npm run start:node:native
```

### 节点( 瓦斯, 内存)

```js
// node-wasm.mjs (Node ESM)
import sqlite3InitModule from '@dao-xyz/sqlite3-vec/wasm';

const sqlite3 = await sqlite3InitModule({
  print: console.log,
  printErr: console.error,
});

// In-memory DB only
const db = new sqlite3.oo1.DB();

// Confirm sqlite-vec is present
const s = db.prepare('select vec_version() as v');
s.step();
console.log('sqlite-vec', s.get({}).v);
s.finalize();

// Minimal vec demo
db.exec('CREATE VIRTUAL TABLE v USING vec0(vector float[3])');
const toVec = () =>
  Uint8Array.from({ length: 3 }, () => Math.floor(Math.random() * 256));
const ins = db.prepare('INSERT INTO v(rowid,vector) VALUES(?1,?2)');
for (let i = 1; i <= 3; i++) ins.bind({ 1: i, 2: toVec().buffer }).stepReset();
ins.finalize();

const probe = toVec();
const q = db.prepare(
  'SELECT rowid, vec_distance_l2(vector, ?1) AS d FROM v ORDER BY d LIMIT 2',
);
q.bind({ 1: probe.buffer });
while (q.step()) console.log(q.get());
q.finalize();
db.close();
```

### 排除本地扩展( 节点)

-   错误 : `undefined symbol: sqlite3_<something>_init`
    
    -   装入器现在尝试标准切入点,顺序为: `sqlite3_extension_init`, (中文(简体) ), `sqlite3_sqlitevec_init`, (中文(简体) ), `sqlite3_vec_init`,则 返回到文件名生成的默认值。 设定 `SQLITE3_VEC_DEBUG=1` 来看 尝试了.
    -   在此软件包下确保二进制 `dist/native/` 匹配您的平台 三重(例如, `linux-x64-gnu`, (中文(简体) ), `linux-arm64-musl`, (中文(简体) ), `darwin-arm64`(中文(简体) ).
    -   您可以通过 `createDatabase({ loadExtension: '/abs/path/sqlite-vec-<triple>.<ext>' })`。 。 。 .
-   在节点绑定矢量
    
    -   你可以通过 `ArrayBuffer`将转换为 节点 `Buffer` 自动为 BLOB 列。 示例 `ins.run([id, float32.buffer])`。 。 。 .

## 安装

```bash
npm install @dao-xyz/sqlite3-vec
```

## 使用此软件包的项目

发布到 npm 时为 `@dao-xyz/sqlite3-vec`你可以浏览 [npm 受抚养人](https://www.npmjs.com/browse/depended/@dao-xyz/sqlite3-vec) 改为 发现使用它的项目.

## 许可证

阿帕奇2.0 (英语).

## 鸣谢

该项目的基础是: [SQLite 瓦斯](https://sqlite.org/wasm),哪个 方便地包装成一个ES模块,并在顶部上再建. 上游软件包是 已发布为 npm [`@sqlite.org/sqlite-wasm`](https://www.npmjs.com/package/@sqlite.org/sqlite-wasm)。 。 。 .

[较好的sqlite3](https://www.npmjs.com/package/better-sqlite3) 用于 本地节点.js支持.

## 常见问题

### @dao-xyz/sqlite3-vec 是什么？

统一 SQLite \+ sqlite-vec 跨越浏览器\(Wasm\)和节点\(native\)\.

### 如何安装 @dao-xyz/sqlite3-vec？

在项目目录运行 npm install @dao-xyz/sqlite3-vec，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 sqlite3-vec，可以用 npx sqlite3-vec 直接运行。

### @dao-xyz/sqlite3-vec 支持 TypeScript 吗？

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

### @dao-xyz/sqlite3-vec 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dao-xyz/sqlite3-vec 可以商用吗？

@dao-xyz/sqlite3-vec 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @dao-xyz/sqlite3-vec 的下载量有多少？

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

### @dao-xyz/sqlite3-vec 还在维护吗？

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