xuguopeng/rrweb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: revamp installation docs for esm and umd (#1788)

Browse Source 
* docs: revamp installation docs for esm and umd

Document recommended install paths across the main guides and package
READMEs for rrweb, @rrweb/all, @rrweb/record, @rrweb/replay, and
rrweb-player.

Clarify three usage modes: bundler/npm, browser no-build with
import maps and +esm, and legacy UMD fallback.

* Apply suggestions from code review

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Apply formatting changes

* Apply suggestion from @eoghanmurray

Co-authored-by: Eoghan Murray <eoghan@getthere.ie>

* Apply formatting changes

* docs(all): streamline README usage section

Move the guide link next to the import example and remove the
duplicated Usage section to keep docs concise and easier to scan.

* docs(readme): update gzip size badges in zh-cn readme

* docs(plugins): update readme imports to scoped esm packages

Replace `rrweb` default imports and `rrweb.Replayer` usage with
`@rrweb/record` `record` and `@rrweb/replay` `Replayer` in plugin
usage examples.

Also update canvas WebRTC plugin imports to scoped `@rrweb/*`
package names to keep docs aligned with current package structure.

* docs: update docs to prefer scoped esm packages

replace `rrweb` default import examples with `@rrweb/record` and
`@rrweb/replay` across recipes and guides in en/zh-CN.

clarify package selection for new integrations, add `@rrweb/all`
convenience guidance, and refresh CDN/style import snippets for ESM and legacy UMD compatibility.

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Eoghan Murray <eoghan@getthere.ie>
This commit is contained in:
Justin Halsall
2026-04-01 12:00:00 +08:00
committed by GitHub
parent 1b6a8be870
commit aab4c553cb
37 changed files with 667 additions and 217 deletions
Download Patch File Download Diff File Expand all files Collapse all files

200
guide.zh_CN.md
View File

@@ -4,56 +4,119 @@
## 安装
### 直接通过 `<script>` 引入
| 目标 | 推荐包 |
| ------------------------- | --------------------------------- |
| 大多数项目（录制 + 回放） | `@rrweb/record` + `@rrweb/replay` |
| 单包便捷接入 | `@rrweb/all` |
| 仅遗留兼容 | `rrweb` |
推荐通过 jsdelivr 的 CDN 安装：
在绝大多数生产架构中，录制端和回放端运行在不同的运行时/页面。请在被录制应用中安装 `@rrweb/record`，在回放应用中安装 `@rrweb/replay`（或 `rrweb-player`）。除非有明确的高级场景，一般不要在同一页面同时引入两者。
```html
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/rrweb@latest/dist/style.css"
/>
<script src="https://cdn.jsdelivr.net/npm/rrweb@latest/umd/rrweb.min.js"></script>
### 1) Bundler / npm（推荐）
```shell
npm install @rrweb/record @rrweb/replay
```
也可以在 URL 中指定具体的版本号，例如：
```html
<script src="https://cdn.jsdelivr.net/npm/rrweb@2.0.0-alpha.21/umd/rrweb.min.js"></script>
```js
import { record } from '@rrweb/record';
import { Replayer } from '@rrweb/replay';
import '@rrweb/replay/dist/style.css';
```
#### 仅引入录制部分
如果你希望使用单一入口，也可以使用便捷包 `@rrweb/all`：
rrweb 代码分为录制和回放两部分，大多数时候用户在被录制的应用中只需要引入录制部分代码。同样可以通过使用 @rrweb/record 包和 CDN 服务来实现：
```html
<script src="https://cdn.jsdelivr.net/npm/@rrweb/record@latest/umd/record.min.js"></script>
```shell
npm install @rrweb/all
```
录制端的 UMD build 会暴露全局变量 `rrwebRecord`。
```js
import { record, Replayer } from '@rrweb/all';
import '@rrweb/all/dist/style.css';
```
#### 仅引入回放部分
`require(...)` / CommonJS 仍可作为兼容方案使用（由各包的 `exports`/`main` 提供），但 2.x 的主路径是 ESM。
### 2) 无 Bundler 的浏览器场景（推荐 no-build）
推荐使用 ES modules + import map + jsDelivr `+esm`：
```html
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/@rrweb/replay@latest/dist/style.css"
/>
<script src="https://cdn.jsdelivr.net/npm/@rrweb/replay@latest/umd/replay.min.js"></script>
<script type="importmap">
{
"imports": {
"@rrweb/record": "https://cdn.jsdelivr.net/npm/@rrweb/record@latest/+esm",
"@rrweb/replay": "https://cdn.jsdelivr.net/npm/@rrweb/replay@latest/+esm"
}
}
</script>
<script type="module">
import { record } from '@rrweb/record';
record({
emit(event) {
console.log(event);
},
});
</script>
```
回放端的 UMD build 会暴露全局变量 `rrwebReplay`。
也可以通过 `@rrweb/all` 便捷引入：
```html
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/@rrweb/all@latest/dist/style.css"
/>
<script type="importmap">
{
"imports": {
"@rrweb/all": "https://cdn.jsdelivr.net/npm/@rrweb/all@latest/+esm"
}
}
</script>
<script type="module">
import { record, Replayer } from '@rrweb/all';
</script>
```
### 3) 传统直接 `<script>` 引入（Legacy / UMD 兼容）
仅在不支持 ESM 的兼容场景中建议使用。
```html
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/rrweb@2.0.0-alpha.20/dist/style.css"
/>
<script src="https://cdn.jsdelivr.net/npm/rrweb@2.0.0-alpha.20/umd/rrweb.min.js"></script>
```
该 UMD 构建会暴露全局变量 `rrweb`。
仅录制 / 仅回放的 UMD 兼容包：
```html
<script src="https://cdn.jsdelivr.net/npm/@rrweb/record@2.0.0-alpha.20/umd/record.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@rrweb/replay@2.0.0-alpha.20/umd/replay.min.js"></script>
```
对应全局变量分别是 `rrwebRecord` 和 `rrwebReplay`。
#### 其他包
除了 `rrweb` 和 `@rrweb/record` 包之外，rrweb 还提供了其他不同用途的包。
除了 `@rrweb/record` 和 `@rrweb/replay` 包之外，rrweb 还提供了其他不同用途的包。
- [rrweb](packages/rrweb)：rrweb 的核心包，包括录制和回放功能。
- [rrweb-player](packages/rrweb-player)：rrweb 的图形用户界面，提供时间线和暂停、快进、加速等按钮。
- [rrweb-snapshot](packages/rrweb-snapshot)：处理快照和重建功能，将 DOM 及其状态转换为可序列化的数据结构。
- [rrdom](packages/rrdom)：rrweb 的虚拟 dom 包。
- [rrdom-nodejs](packages/rrdom-nodejs)：用于服务器端 DOM 操作的 rrdom 的 Node.js 版本。
- [@rrweb/all](packages/all)：一个包含 `rrweb` 和 `@rrweb/packer`，便于安装的包。
- [@rrweb/all](packages/all)：一个包含 `rrweb` 和 `@rrweb/packer` 的便捷包。
- [@rrweb/record](packages/record)：一个用于录制 rrweb 会话的包。
- [@rrweb/replay](packages/replay)：一个用于回放 rrweb 会话的包。
- [@rrweb/packer](packages/packer)：一个用于打包和解包 rrweb 数据的包。
@@ -68,14 +131,6 @@ rrweb 代码分为录制和回放两部分，大多数时候用户在被录制
- [@rrweb/rrweb-plugin-canvas-webrtc-record](packages/plugins/rrweb-plugin-canvas-webrtc-record)：一个用于通过 WebRTC 流式传输 `<canvas>` 的插件。
- [@rrweb/rrweb-plugin-canvas-webrtc-replay](packages/plugins/rrweb-plugin-canvas-webrtc-replay)：一个用于通过 WebRTC 播放流式 `<canvas>` 的插件。
### 通过 npm 引入
```shell
npm install --save rrweb
```
rrweb 同时提供 commonJS 和 ES modules 两种格式的打包文件，易于和常见的打包工具配合使用。
### 兼容性
由于使用 `MutationObserver` API，rrweb 不支持 IE11 以下的浏览器。可以从[这里](https://caniuse.com/#feat=mutationobserver)找到兼容的浏览器列表。
@@ -84,10 +139,14 @@ rrweb 同时提供 commonJS 和 ES modules 两种格式的打包文件，易于
### 录制
如果通过 `<script>` 的方式仅引入录制部分，那么可以访问到全局变量 `rrwebRecord`，它和全量引入时的 `rrweb.record` 使用方式完全一致，以下示例代码将使用后者。
现代用法建议直接使用 `@rrweb/record` 的 `record`：
```js
rrweb.record({
import { record } from '@rrweb/record';
```
```js
record({
emit(event) {
// 用任意方式存储 event
},
@@ -99,7 +158,7 @@ rrweb 在录制时会不断将各类 event 传递给配置的 emit 方法，你
调用 `record` 方法将返回一个函数，调用该函数可以终止录制：
```js
let stopFn = rrweb.record({
let stopFn = record({
emit(event) {
if (events.length > 100) {
// 当事件数量大于 100 时停止录制
@@ -114,7 +173,7 @@ let stopFn = rrweb.record({
```js
let events = [];
rrweb.record({
record({
emit(event) {
// 将 event 存入 events 数组中
events.push(event);
@@ -140,7 +199,7 @@ setInterval(save, 10 * 1000);
#### 配置参数
`rrweb.record(config)` 的 config 部分接受以下参数
`record(config)` 的 config 部分接受以下参数
| key | 默认值 | 功能 |
| ------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -192,7 +251,7 @@ setInterval(save, 10 * 1000);
// 使用二维数组来存放多个 event 数组
const eventsMatrix = [[]];
rrweb.record({
record({
emit(event, isCheckout) {
// isCheckout 是一个标识，告诉你重新制作了快照
if (isCheckout) {
@@ -227,7 +286,7 @@ window.onerror = function () {
// 使用二维数组来存放多个 event 数组
const eventsMatrix = [[]];
rrweb.record({
record({
emit(event, isCheckout) {
// isCheckout 是一个标识，告诉你重新制作了快照
if (isCheckout) {
@@ -258,28 +317,36 @@ window.onerror = function () {
### 回放
回放时需要引入对应的 CSS 文件：
在 bundler 场景下，可在入口文件中引入 CSS：
```js
import '@rrweb/replay/dist/style.css';
```
在浏览器 no-build 场景下，也可以在 HTML 中引入 CSS：
```html
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/rrweb@latest/dist/style.css"
href="https://cdn.jsdelivr.net/npm/@rrweb/replay@latest/dist/style.css"
/>
```
再通过以下 JS 代码初始化 replayer：
然后通过以下 JS 代码初始化 replayer：
```js
import { Replayer } from '@rrweb/replay';
const events = YOUR_EVENTS;
const replayer = new rrweb.Replayer(events);
const replayer = new Replayer(events);
replayer.play();
```
#### 使用 API 控制回放
```js
const replayer = new rrweb.Replayer(events);
const replayer = new Replayer(events);
// 播放
replayer.play();
@@ -299,7 +366,7 @@ replayer.destroy();
#### 配置参数
可以通过 `new rrweb.Replayer(events, options)` 的方式向 rrweb 传递回放时的配置参数，具体配置如下：
可以通过 `new Replayer(events, options)` 的方式向 rrweb 传递回放时的配置参数，具体配置如下：
| key | 默认值 | 功能 |
| ------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -327,25 +394,44 @@ rrweb 自带的回放只提供所有的 JS API 以及最基本的 UI，如果需
##### 安装
rrweb-player 同样可以使用 CDN 方式安装：
Bundler / npm（推荐）：
```shell
npm install rrweb-player
```
```js
import rrwebPlayer from 'rrweb-player';
import 'rrweb-player/dist/style.css';
```
无 bundler 的浏览器场景（ESM + import maps）：
```html
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/rrweb-player@latest/dist/style.css"
/>
<script src="https://cdn.jsdelivr.net/npm/rrweb-player@latest/umd/rrweb-player.js"></script>
<script type="importmap">
{
"imports": {
"rrweb-player": "https://cdn.jsdelivr.net/npm/rrweb-player@latest/+esm"
}
}
</script>
<script type="module">
import rrwebPlayer from 'rrweb-player';
</script>
```
或者通过 npm 安装：
Legacy 直接 `<script>` 引入（UMD 兼容）：
```shell
npm install --save rrweb-player
```
```js
import rrwebPlayer from 'rrweb-player';
import 'rrweb-player/dist/style.css';
```html
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/rrweb-player@2.0.0-alpha.20/dist/style.css"
/>
<script src="https://cdn.jsdelivr.net/npm/rrweb-player@2.0.0-alpha.20/umd/rrweb-player.min.js"></script>
```
##### 使用
@@ -373,16 +459,16 @@ new rrwebPlayer({
| speedOption | [1, 2, 4, 8] | 倍速播放可选值 |
| showController | true | 是否显示播放器控制 UI |
| tags | {} | 可以以 key value 的形式展示自定义事件在时间轴上的颜色 |
| ... | - | 其它所有 rrweb Replayer 的配置参数均可透传 |
| ... | - | 其它所有 Replayer 的配置参数均可透传 |
#### 事件
开发者可能希望监听回放时的各类事件，例如在跳过无用户操作的时间时给用户一些提示。
rrweb 的 Replayer 提供了 `on` API 用于提供该功能
Replayer 提供了 `on` API 用于实现该功能
```js
const replayer = new rrweb.Replayer(events);
const replayer = new Replayer(events);
replayer.on(EVENT_NAME, (payload) => {
...
})