跳到主要内容

安装与初始化

本页给出完整的依赖清单、两种适配器的初始化示例,以及 Worker、WASM、Vite 的配套配置。想先跑最小示例,请回到 快速开始。

核心依赖​

npm install @aiao/rxdb @aiao/utils

数据库适配器​

二选一即可,也可以按场景混用。

SQLite 适配器(推荐)​

轻量、兼容性最好,覆盖大多数浏览器端结构化数据场景:

npm install @aiao/rxdb-adapter-wa-sqlite

PGlite 适配器​

浏览器内的 PostgreSQL,适合复杂查询与扩展需求:

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

两者的能力对比与选型建议,见 SQLite 适配器 与 PGlite 适配器。

框架集成(按需)​

# React
npm install @aiao/rxdb-react

# Vue 3
npm install @aiao/rxdb-vue

# Angular
npm install @aiao/rxdb-angular

只做链路验证时,不需要额外的测试包或示例实体包。

快速初始化​

SQLite 适配器​

import { Entity, EntityBase, PropertyType, RxDB, SyncType } from '@aiao/rxdb';
import { RxDBAdapterWaSqlite } from '@aiao/rxdb-adapter-wa-sqlite';
import { checkOPFSAvailable } from '@aiao/utils';

@Entity({
  name: 'Todo',
  properties: [
    { name: 'title', type: PropertyType.string, required: true },
    { name: 'completed', type: PropertyType.boolean, default: false }
  ]
})
class Todo extends EntityBase {}

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

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

    return new RxDBAdapterWaSqlite(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('wa-sqlite');
  return rxdb;
}

PGlite 适配器​

import { Entity, EntityBase, PropertyType, RxDB, SyncType } from '@aiao/rxdb';
import { RxDBAdapterPGlite } from '@aiao/rxdb-adapter-pglite';
import { PGlite } from '@electric-sql/pglite';

@Entity({
  name: 'Todo',
  properties: [
    { name: 'title', type: PropertyType.string, required: true },
    { name: 'completed', type: PropertyType.boolean, default: false }
  ]
})
class Todo extends EntityBase {}

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-wa-sqlite';

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

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

import { SqliteSharedWorker } from '@aiao/rxdb-adapter-wa-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: {
    format: 'es'
  },
  publicDir: 'public',

  // 启用 OPFS 需要这组 HTTP 头,否则 SharedArrayBuffer 不可用
  server: {
    headers: {
      'Cross-Origin-Opener-Policy': 'same-origin',
      'Cross-Origin-Embedder-Policy': 'require-corp'
    }
  },

  optimizeDeps: {
    exclude: ['@aiao/rxdb-adapter-wa-sqlite', '@aiao/rxdb-adapter-pglite']
  }
});

注意事项​

Worker 与 WASM 路径​

  • Worker 文件须用 new URL('./worker.ts', import.meta.url) 形式引用
  • WASM 路径要和 public 目录下的实际路径对齐
  • 构建工具(Vite、Webpack 等)需要识别这些资源引用

HTTP 头​

使用 OPFS 时必须配置以下响应头,否则 SharedArrayBuffer 不可用:

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

浏览器支持​

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

示例项目​

想看完整配置,直接参考仓库里的三个 demo:

  • apps/dev-rxdb-angular
  • apps/dev-rxdb-react
  • apps/dev-rxdb-vue

下一步​