跳到主要内容

安装

核心依赖​

安装 RxDB 核心包：

npm install @aiao/rxdb @aiao/utils

数据库适配器​

SQLite 适配器（推荐）​

轻量级，兼容性最好：

npm install @aiao/rxdb-adapter-sqlite

PGlite 适配器​

功能强大，支持完整 PostgreSQL：

npm install @aiao/rxdb-adapter-pglite @electric-sql/pglite

详细对比请查看 PGlite 适配器文档 和 SQLite 适配器文档。

框架集成（可选）​

根据使用的框架选择对应的集成包：

# React
npm install @aiao/rxdb-react

# Vue 3
npm install @aiao/rxdb-vue

# Angular
npm install @aiao/rxdb-angular

开发工具（可选）​

测试工具和示例实体：

npm install @aiao/rxdb-test -D

快速初始化​

使用 SQLite 适配器​

创建一个最小可运行的 RxDB 实例：

import { RxDB, SyncType } from '@aiao/rxdb';
import { RxDBAdapterSqlite, SqliteOptions } from '@aiao/rxdb-adapter-sqlite';
import { checkOPFSAvailable } from '@aiao/utils';

// 1. 定义或导入实体模型
// 使用测试包中的实体
import { Todo } from '@aiao/rxdb-test/entities';

// 或者定义自己的实体：
// import { Entity, EntityBase, PropertyType  } from '@aiao/rxdb';
//
// @Entity({
//   name: 'Todo',
//   properties: [
//     { name: 'title', type: PropertyType.string, required: true },
//     { name: 'completed', type: PropertyType.boolean, default: false },
//     { name: 'createdAt', type: PropertyType.date }
//   ]
// })
// export class Todo extends EntityBase {}

// 2. 创建 RxDB 实例
export async function createRxdb() {
  const rxdb = new RxDB({
    dbName: 'demo',
    entities: [Todo],
    sync: {
      local: { adapter: 'sqlite' },
      type: SyncType.None
    }
  });

  // 3. 注册适配器（根据浏览器能力选择最优配置）
  rxdb.adapter('sqlite', async db => {
    let options: SqliteOptions;
    const available = await checkOPFSAvailable();

    if (available) {
      // OPFS + Worker（最佳性能）
      options = {
        vfs: 'OPFSCoopSyncVFS',
        worker: true,
        workerInstance: new Worker(
          new URL('./sqlite.worker', import.meta.url),
          { type: 'module', name: 'rxdb-worker' }
        ),
        wasmPath: '/wa-sqlite/wa-sqlite.wasm'
      };
    } else {
      // IDB + SharedWorker（最佳兼容性）
      options = {
        vfs: 'IDBBatchAtomicVFS',
        sharedWorker: true,
        sharedWorkerInstance: new SharedWorker(
          new URL('./sqlite-shared.worker', import.meta.url),
          { type: 'module', name: 'rxdb-shared-worker' }
        ),
        wasmPath: '/wa-sqlite/wa-sqlite-async.wasm'
      };
    }

    return new RxDBAdapterSqlite(db, options);
  });

  // 4. 连接数据库（首次连接会自动创建系统表与实体表）
  await rxdb.connect('sqlite').toPromise();

  return rxdb;
}

使用 PGlite 适配器​

import { RxDB, SyncType } from '@aiao/rxdb';
import { RxDBAdapterPGlite } from '@aiao/rxdb-adapter-pglite';
import { PGlite } from '@electric-sql/pglite';
import { Todo } from '@aiao/rxdb-test/entities';

export async function createRxdb() {
  const rxdb = new RxDB({
    dbName: 'demo',
    entities: [Todo],
    sync: {
      local: { adapter: 'pglite' },
      type: SyncType.None
    }
  });

  // 注册 PGlite 适配器
  rxdb.adapter('pglite', async db => {
    const pg = await PGlite.create({
      dataDir: `idb://rxdb-${db.dbName}`
    });

    return new RxDBAdapterPGlite(db, pg);
  });

  await rxdb.connect('pglite').toPromise();

  return rxdb;
}

Worker 文件配置​

SQLite Worker 文件​

sqlite.worker.ts (用于 OPFS)​

import { SqliteWorker } from '@aiao/rxdb-adapter-sqlite';

const worker = new SqliteWorker();
worker.listen();

sqlite-shared.worker.ts (用于 IDB)​

import { SqliteSharedWorker } from '@aiao/rxdb-adapter-sqlite';

const worker = new SqliteSharedWorker();
worker.listen();

静态资源配置​

WASM 文件​

将 wa-sqlite WASM 文件放到项目的 public 目录：

public/
  wa-sqlite/
    wa-sqlite.wasm           # 用于 OPFS
    wa-sqlite-async.wasm     # 用于 IDB

可以从 wa-sqlite releases 下载最新版本。

Vite 配置​

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  // 配置 Worker 支持
  worker: {
    format: 'es'
  },

  // 配置静态资源目录
  publicDir: 'public',

  // 如果使用 OPFS，需要配置 HTTP 头
  server: {
    headers: {
      'Cross-Origin-Opener-Policy': 'same-origin',
      'Cross-Origin-Embedder-Policy': 'require-corp'
    }
  },

  // 优化配置
  optimizeDeps: {
    exclude: [
      '@aiao/rxdb-adapter-sqlite',
      '@aiao/rxdb-adapter-pglite'
    ]
  }
});

注意事项​

Worker 和 WASM 路径​

  • Worker 文件需要使用 new URL('./worker.ts', import.meta.url) 语法
  • WASM 路径需要对应 public 目录中的实际路径
  • 构建工具（Vite、Webpack 等）需要正确处理这些资源

HTTP 头配置​

如果使用 OPFS 模式，需要配置以下 HTTP 响应头：

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

否则会导致 SharedArrayBuffer 不可用。

浏览器支持​

  • 最低要求: Chrome 90+, Edge 90+, Safari 14+, Firefox 88+
  • 推荐版本: Chrome 102+, Edge 102+, Safari 15.2+, Firefox 111+ (支持 OPFS)

下一步​

安装完成后，你可以：

示例项目​

参考演示项目了解完整配置：

  • apps/dev-rxdb-angular - Angular 示例
  • apps/dev-rxdb-react - React 示例
  • apps/dev-rxdb-vue - Vue 示例