# @basepurpose/rxdb-sqlite 中文文档

规范地址：https://npmcn.com/package/%40basepurpose/rxdb-sqlite/

版本：0\.1\.0
npm 元数据更新时间：2026-04-29T07:08:39.326Z
中文译文更新时间：2026-11-07T20:17:44.855Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：671 kB，119 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：0 个
- peer 依赖：rxdb \>=15\.0\.0，rxjs \>=7\.0\.0
- 首次发布：2026-04-29T07:08:38.860Z
- 最新版本发布：2026-04-29T07:08:39.125Z
- 近 30 天下载量：2647（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 1 个）

## 中文简介

RxDB 自由、开源、跨平台的 SQLite 存储适配器

## 安装

```sh
npm install @basepurpose/rxdb-sqlite
```

也可以使用：`pnpm add @basepurpose/rxdb-sqlite`、`yarn add @basepurpose/rxdb-sqlite`、`bun add @basepurpose/rxdb-sqlite`

## README

# @ base目的/rxdb-sqlite

> 一个自由、开源、跨平台的 SQLite 存储适配器 [RxDB 函数](https://rxdb.info/)

[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://npmcn.com/package/%40basepurpose/rxdb-sqlite/LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/) [![RxDB](https://img.shields.io/badge/RxDB-15.0+-green.svg)](https://rxdb.info/)

> **寻找官方,生产优化的SQLite存储器?** 见 [RxDB 高精度 SQLite](https://rxdb.info/rx-storage-sqlite.html)。 。 。 .
> 
> 这是一个 **社区建设** 列入 `@basepurpose`。 。 。 .

## 为什么这个存在

[RxDB 函数](https://rxdb.info/) 是JavaScript应用程序的优秀本地第一,离线能力数据库. 其生产准备的SQLite存储需要付费的溢价许可证,这可能成为独行开发者,创业者,开源项目,学生,以及非营利者的障碍.

该项目提供 **免费,麻省理工学院许可** SQLite存储适配器在多个平台之间工作.

## 平台支持

| 平台 | SQLite 执行 | 测试状态 |
| --- | --- | --- |
| 原生反应( Android) | expo- sqlite 语句 | 在设备上验证 |
| 原生反应( iOS) | expo- sqlite 语句 | 测试通过、需要设备核查 |
| 浏览器 | @sqlite.org/sqlite-wasm + OPFS | 测试通过、需要设备核查 |
| 节点.js | 较好的sqlite3 | 测试通过、需要设备核查 |
| 阿宝 | bun: sqlite (本地语) | 测试通过、需要设备核查 |
| 电子 | 较好的sqlite3 | 测试通过、需要设备核查 |
| 电容(iOS/Android) | @ mictor- community/ sqlite | 测试通过、需要设备核查 |
| Tauri (温道/macOS/Linux) | @tauri-apps/plugin-sql (中文(简体) ) | 测试通过、需要设备核查 |

671个测试通过28个测试套房. 目前为止,只有Android上的React Industrial已经通过真实设备验证. **欢迎社区帮助测试其他平台** 请 [打开一个问题](https://github.com/basepurpose/rxdb-sqlite/issues) 你的结果.

## 安装

```bash
npm install @basepurpose/rxdb-sqlite
```

### 平台特定依赖

| 平台 | 额外安装 |
| --- | --- |
| 浏览器 | 无(WASM捆绑) |
| 节点.js | `npm install better-sqlite3` |
| 阿宝 | 无( 本地 SQLite) |
| 原生反应 | `npx expo install expo-sqlite` |
| 电子 | `npm install better-sqlite3` |
| 电容 | `npm install @capacitor-community/sqlite && npx cap sync` |
| 陶里语Name | 添加 `tauri-plugin-sql` 改为 `Cargo.toml` |

## 快速启动

```typescript
import { createRxDatabase } from 'rxdb';
import { getRxStorageSQLite } from '@basepurpose/rxdb-sqlite';

const db = await createRxDatabase({
  name: 'mydb',
  storage: getRxStorageSQLite()
});

await db.addCollections({
  users: {
    schema: {
      version: 0,
      primaryKey: 'id',
      type: 'object',
      properties: {
        id: { type: 'string', maxLength: 100 },
        name: { type: 'string' },
        email: { type: 'string' }
      },
      required: ['id', 'name']
    }
  }
});

await db.users.insert({ id: 'user-1', name: 'Alice', email: 'alice@example.com' });
```

### 平台特定导入

```typescript
// Browser (WASM + OPFS)
import { getRxStorageSQLite } from '@basepurpose/rxdb-sqlite/browser';

// Node.js
import { getRxStorageSQLite } from '@basepurpose/rxdb-sqlite/node';

// Bun
import { getRxStorageSQLite } from '@basepurpose/rxdb-sqlite/bun';

// React Native (Expo)
import { getRxStorageSQLite } from '@basepurpose/rxdb-sqlite/react-native';

// Electron
import { getRxStorageSQLite } from '@basepurpose/rxdb-sqlite/electron';

// Capacitor (iOS/Android)
import { getRxStorageSQLite } from '@basepurpose/rxdb-sqlite/capacitor';

// Tauri (Desktop)
import { getRxStorageSQLite } from '@basepurpose/rxdb-sqlite/tauri';
```

## 特征

### 芒果查询支持

所有标准 RxDB 查询操作员的工作 :

```typescript
const results = await db.users.find({
  selector: {
    $and: [
      { age: { $gte: 18 } },
      { status: { $in: ['active', 'pending'] } },
      { 'address.country': 'US' }
    ]
  },
  sort: [{ name: 'asc' }],
  limit: 10
}).exec();
```

**支持的运算符 :** `$eq`, (中文(简体) ), `$ne`, (中文(简体) ), `$gt`, (中文(简体) ), `$gte`, (中文(简体) ), `$lt`, (中文(简体) ), `$lte`, (中文(简体) ), `$in`, (中文(简体) ), `$nin`, (中文(简体) ), `$exists`, (中文(简体) ), `$type`, (中文(简体) ), `$and`, (中文(简体) ), `$or`, (中文(简体) ), `$not`, (中文(简体) ), `$nor`, (中文(简体) ), `$elemMatch`, (中文(简体) ), `$size`, (中文(简体) ), `$all`, (中文(简体) ), `$regex`, (中文(简体) ), `$text`

### 反应查询

```typescript
db.users.find().$.subscribe(users => {
  console.log('Users updated:', users);
});
```

### 附录

将二进制数据与文档并存 :

```typescript
const doc = await db.posts.findOne('post-1').exec();
await doc.putAttachment({
  id: 'image.jpg',
  data: imageBase64String,
  type: 'image/jpeg'
});
```

### 全文搜索( FTS5)

```typescript
const schema = {
  // ... your schema
  fulltext: {
    fields: ['title', 'content'],
    tokenizer: 'unicode61' // 'unicode61' | 'porter' | 'ascii' | 'trigram'
  }
};

const results = await db.articles.find({
  selector: { $text: 'javascript tutorial' }
}).exec();
```

### 索引顾问

分析查询并获取索引建议:

```typescript
import { analyzeQuery, suggestIndexes } from '@basepurpose/rxdb-sqlite';

const suggestions = suggestIndexes(
  { selector: { status: 'active', age: { $gte: 18 } } },
  'users'
);
```

### 复制

与所有 RxDB 复制插件( CouchDB, Supabase, GraphQL等) 一起工作 :

```typescript
import { replicateCouchDB } from 'rxdb/plugins/replication-couchdb';

const replication = replicateCouchDB({
  collection: db.users,
  url: 'https://your-couchdb.example.com/users',
  live: true,
  pull: {},
  push: {}
});
```

### 多标签支持( 浏览器)

通过 BroadcastChannel 自动同步到其他标签的更改 .

### RxDB 插件兼容性

与CRDT,加密,复制,备份,和迁移插件一起工作.

## 配置

```typescript
getRxStorageSQLite({
  debug: true,

  pragma: {
    journal_mode: 'WAL',
    synchronous: 'NORMAL',
    cache_size: -64000,   // 64MB cache
    temp_store: 'MEMORY'
  }
});
```

## API 参考

### `getRxStorageSQLite(options?)`

创建 RxStorage 实例。 平台是自动检测的,或者使用特定平台的导入.

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `debug` | `boolean` | 启用调试记录( 默认 ): `false`(中文(简体) ) |
| `adapter` | `SQLiteAdapterFactory` | 自定义适配器厂 |
| `pragma` | `SQLitePragmaSettings` | SQLite PRAGMA 设置 |
| `browser` | `BrowserAdapterOptions` | 浏览器特定选项 |
| `capacitor` | `CapacitorAdapterOptions` | 特定电容选项 |
| `tauri` | `TauriAdapterOptions` | Tauri特定选项 |
| `node` | `NodeAdapterOptions` | 节点.js 特定选项 |
| `bun` | `BunAdapterOptions` | Bun 特定选项 |
| `reactNative` | `ReactNativeAdapterOptions` | 对应本地特定选项 |
| `electron` | `ElectronAdapterOptions` | 电子专用选项 |

### 工具函数

```typescript
import {
  closeAllSQLiteConnections,
  isDatabaseOpen,
  translateMangoToSQL,
  buildSelectQuery,
  buildCountQuery,
} from '@basepurpose/rxdb-sqlite';
```

### 浏览器要求

为了达到最佳性能,请使用这些信头,以启用共享箭头:

```
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
```

如果这些信头不可用,存储会回到更慢的模式.

### 错误代码

| 代码 | 说明 |
| --- | --- |
| `SQLITE_STORAGE_CLOSED` | 关闭实例操作 |
| `SQLITE_ATTACHMENT_NOT_FOUND` | 并不存在附件 |
| `SQLITE_DIGEST_MISMATCH` | 附件摘要校验失败 |
| `SQLITE_INVALID_DOCUMENT_ID` | 无效的文档 ID |
| `MANGO_QUERY_ERROR` | 无效的查询运算符或语法 |

## 捐款

欢迎捐款。 见 [捐款额](https://npmcn.com/package/%40basepurpose/rxdb-sqlite/CONTRIBUTING.md) 准则.

```bash
git clone https://github.com/basepurpose/rxdb-sqlite.git
cd rxdb-sqlite
bun install
bun test
bun run build
```

## 许可证

麻省理工学院 -- -- 见 [自由主义](https://npmcn.com/package/%40basepurpose/rxdb-sqlite/LICENSE)。 。 。 .

## 承认

-   [RxDB 函数](https://rxdb.info/) - 数据库中的存储权限
-   [@sqlite.org/sqlite-wasm (英语)](https://sqlite.org/wasm) - 官方 SQLite WASM 构建
-   [@ mictor- community/ sqlite](https://github.com/capacitor-community/sqlite) -- 电容 SQLite 插件
-   [@tauri-apps/plugin-sql (中文(简体) )](https://v2.tauri.app/plugin/sql/) -- Tauri SQL 插件

## 由新建

[基准用途](https://github.com/basepurpose) ——造型实验室建设开源工具.

## 常见问题

### @basepurpose/rxdb-sqlite 是什么？

RxDB 自由、开源、跨平台的 SQLite 存储适配器

### 如何安装 @basepurpose/rxdb-sqlite？

在项目目录运行 npm install @basepurpose/rxdb-sqlite，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：rxdb（\>=15\.0\.0）、rxjs（\>=7\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @basepurpose/rxdb-sqlite 支持 TypeScript 吗？

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

### @basepurpose/rxdb-sqlite 支持 ESM 还是 CommonJS？

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

### @basepurpose/rxdb-sqlite 需要什么版本的 Node\.js？

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

### @basepurpose/rxdb-sqlite 可以商用吗？

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

### @basepurpose/rxdb-sqlite 的下载量有多少？

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

### @basepurpose/rxdb-sqlite 还在维护吗？

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