跳到主要内容

安装

核心依赖​

安装 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 适配器​

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

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

  rxdb.adapter('sqlite', async db => {
    const available = await checkOPFSAvailable();

    return new RxDBAdapterSqlite(db, {
      vfs: available ? 'OPFSCoopSyncVFS' : 'IDBBatchAtomicVFS',
      worker: available,
      workerInstance:
        available ? new Worker(new URL('./sqlite.worker', import.meta.url), { type: 'module' }) : undefined,
      sharedWorker: !available,
      sharedWorkerInstance:
        !available ?
          new SharedWorker(new URL('./sqlite-shared.worker', import.meta.url), { type: 'module' })
        : undefined,
      wasmPath: available ? '/wa-sqlite/wa-sqlite.wasm' : '/wa-sqlite/wa-sqlite-async.wasm'
    });
  });

  await rxdb.connect('sqlite');
  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 }
  });

  rxdb.adapter('pglite', async db => {
    const pg = await PGlite.create({ dataDir: `idb://rxdb-${db.dbName}` });
    return new RxDBAdapterPGlite(db, pg);
  });

  await rxdb.connect('pglite');
  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 示例