企业官网建设流程全解析

• 数据库
• NoSQL
• 嵌入式数据库
• 实时数据库

RxDB 是一个 local-first 的实时 NoSQL 数据库，能够在浏览器、Node.js、React Native、Electron 等几乎所有 JavaScript 运行时中运行。本文是 RxDB 的官方安装指南，覆盖从 npm 安装主包与 peer 依赖rxjs、为老浏览器补齐 polyfills、修复 Angular/Webpack 场景下global is not defined报错，到项目配置参考、安装最新开发构建以及最终导入并使用createRxDatabase的完整流程。读完本文，你将能够在一个全新项目中快速、稳定地把 RxDB 跑起来，并避开最常见的构建期陷阱。

通过 npm 安装 RxDB

安装最新发布的rxdb主包及其运行时依赖，并保存到package.json，在项目根目录执行：

npm install rxdb

rxdb的 npm 包是双格式（dual package）发布：main指向 CommonJS 产物./dist/cjs/index.js，module指向 ESM 产物./dist/esm/index.js，同时通过exports字段为每个子路径插件提供了独立的types、require和import入口（见仓库根目录 package.json）。因此无论你使用 webpack、Rollup、Vite 还是直接跑在 Node.js 上，都可以被正确解析。

除了 npm，RxDB 官方还维护了其他常见包管理器的安装命令。文档站点中的安装命令由 install-tabs.tsx 这个组件统一渲染，你可以按自己的工具链选择其一：

# yarn yarn add rxdb # pnpm pnpm add rxdb # bun bun add rxdb # deno（通过 npm 兼容层） deno add npm:rxdb

从仓库 package.json 可以看到，当前 RxDB 的engines字段声明"node": ">=20"，因此在 Node.js 环境使用时应确保 Node 版本不低于 20。

安装 peer 依赖：rxjs

RxDB 的响应式能力建立在 RxJS 之上，因此rxjs被声明为peerDependencies（当前版本要求"rxjs": "^7.8.2"，见 package.json）。如果项目里还没有安装过它，必须手动安装：

npm install rxjs

同样的，其他包管理器也适用：

# yarn yarn add rxjs # pnpm pnpm add rxjs # bun bun add rxjs # deno deno add npm:rxjs

之所以是 peer 依赖而不是普通依赖，是为了避免与你的应用直接使用的rxjs版本产生重复实例。RxDB 中几乎所有订阅 API（如RxQuery.$、RxDocument.done$）返回的都是 RxJSObservable，一旦出现两份不同的rxjs副本，类型与行为都可能出现偏差，因此请始终与主包保持同一版本。

为旧浏览器安装 polyfills

RxDB 的源码使用 ES8 编写，编译产物会向下转译到 ES5（这一点从 package.json 的build:cjs脚本cross-env NODE_ENV=es5 babel src --out-dir dist/cjs可以确认）。这意味着在较老的浏览器上，你可能需要引入 polyfill 来补齐 ES8+ 运行时缺失的能力。

官方推荐使用 core-js：

npm i core-js --save

安装后，在应用的入口代码（通常是main.ts或index.js的第一行）中导入：

import 'core-js/stable';

需要注意：polyfill 是全局副作用代码，必须在任何业务模块之前完成导入，且通常只应出现在入口文件中。如果你的目标是现代浏览器或 Node.js 20+ 环境，则不需要这一步。

修复 Webpack 下的global is not defined错误

在 Angular 或其他基于Webpack的框架中使用 RxDB 时，你可能会遇到如下报错：

Uncaught ReferenceError: global is not defined

原因在于：RxDB 的某些依赖（如broadcast-channel、ws等）会假设存在 Node.js 特有的global全局变量，而部分打包器不会在浏览器运行时注入该变量。解决办法是手动在 polyfill 文件中把这两个全局变量补齐，RxDB 的 Angular 示例正是这样做的（见 examples/angular/src/polyfills.ts）：

(window as any).global = window; (window as any).process = { env: { DEBUG: undefined }, };

这段代码做了两件事：

• 把浏览器的window对象挂到global上，满足依赖对 Node 全局变量的假设；
• 补一个最小的process对象，其中env.DEBUG置为undefined，避免依赖读取process.env.DEBUG时抛出异常。

在 Angular 项目中，这段代码应放在src/polyfills.ts中，且位于import 'zone.js'之前；在其他 Webpack 项目中，可以放在webpack.config.js的entry数组最前面，或作为单独的polyfills.ts入口。

项目配置参考：examples 与 config 目录

为了帮助你快速对齐版本与配置，RxDB 仓库内置了两类可直接参考的资源：

• examples 目录存放了经过 CI 测试的完整示例工程，覆盖 Angular、React、React Native、Vue、Svelte、Electron、Flutter、Ionic、Tauri、GraphQL、Supabase、Node 以及 vite-vanilla-ts 等多种框架与运行场景。以 Angular 为例，examples/angular 中包含了src/app/services/database.service.ts（数据库创建服务）、src/app/schemas/hero.schema.ts（集合 schema）以及上文提到的src/polyfills.ts，可以对照学习一个真实可运行的最小 RxDB 应用是如何组织起来的。
• config 目录暴露了项目自身使用的 Webpack、Rollup、Mocha、Karma、TypeScript 等基础配置文件。例如 config/webpack.config.js 展示了 RxDB 官方打包时的 Terser 压缩与 optimization bailout 检测策略，config/tsconfig.types.json 则是类型声明的生成配置。这些文件可以帮助你为 RxDB 定制自己的构建管线。

关于各依赖包的支持版本，请以仓库根目录 package.json 中的dependencies、peerDependencies与devDependencies声明为准。当前版本中，peerDependencies除rxjs外还包括react、vue、@angular/core、@preact/signals-core、firebase、mongodb、nats等——它们全部标记为可选（见peerDependenciesMeta），只有当你实际使用对应插件时才需要安装。

安装最新开发构建（git 依赖）

如果希望使用尚未发布到 npm 的最新开发状态，可以把 RxDB 作为 git 依赖直接写进package.json：

{ "dependencies": { "rxdb": "git+https://git@github.com/pubkey/rxdb.git#commitHash" } }

将commitHash替换为最新一次 build 提交的哈希（仓库的提交记录中搜索 "build" 关键字即可定位，仓库根目录 package.json 的build脚本会执行完整的build:cjs、build:esm、build:types与build:plugins流水线，因此每次构建提交都会产生可用的dist产物）。

这种方式适合想提前尝鲜新特性或验证某个修复的场景；对于正式项目，仍建议使用 npm 上的稳定版本，因为 git 依赖无法保证语义化版本兼容性。

导入与使用 RxDB

一切就绪后，导入rxdb主入口即可使用核心 API。默认入口会导出 RxDB 核心的全部内容，例如创建数据库的函数createRxDatabase（完整导出清单见 src/index.ts）：

import { createRxDatabase, // 详见 docs-src/docs/rx-database.md /* ... */ } from 'rxdb';

从当前版本的 package.json 的exports字段可以看到，RxDB 同时支持按需子路径导入，例如rxdb/plugins/core、rxdb/plugins/storage-dexie、rxdb/plugins/validate-ajv等。官方推荐的做法是只导入你实际需要的插件，配合sideEffects: false声明，让打包器可以更好地做 tree-shaking，从而缩小最终 bundle。

一个最小可运行的数据库创建示例（结合 quickstart 中的用法）：

import { createRxDatabase } from 'rxdb/plugins/core'; import { getRxStorageDexie } from 'rxdb/plugins/storage-dexie'; import { addRxPlugin } from 'rxdb/plugins/core'; import { RxDBDevModePlugin } from 'rxdb/plugins/dev-mode'; // 开发阶段建议开启 dev-mode 插件，获得额外的校验与错误提示 addRxPlugin(RxDBDevModePlugin); const db = await createRxDatabase({ name: 'mydatabase', storage: getRxStorageDexie() });

其中addRxPlugin的插件注册机制实现在 src/plugin.ts：插件通过原型覆盖、overwritable覆盖与钩子注册三种方式扩展 RxDB 核心，且同名插件不可重复注册。关于数据库创建参数的完整说明（name、storage、password、multiInstance、eventReduce等），可以继续阅读 RxDatabase 文档。

安装完成、polyfill 就绪并成功导入createRxDatabase之后，你就已经打通了 RxDB 的第一步。接下来可以按官方 Quickstart 依次完成建集合、插文档、查询、订阅与同步，也可以直接翻阅 examples 中与你技术栈匹配的完整示例工程。

• 数据库
• NoSQL
• 嵌入式数据库
• 实时数据库