# @arms/rum-core 中文文档

规范地址：https://npmcn.com/package/%40arms/rum-core/

版本：0\.1\.12
npm 元数据更新时间：2026-10-27T11:43:05.277Z
中文译文更新时间：2026-11-06T19:55:57.882Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40arms/rum-core
原文对照：https://npmcn.com/package/%40arms/rum-core/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：297 kB，132 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2023-11-02T07:07:58.485Z
- 最新版本发布：2026-10-27T11:43:04.978Z
- 近 30 天下载量：233862（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：53（近 12 个月 12 个）

## 中文简介

朗姆酒 贾瓦斯克花心

## 安装

```sh
npm install @arms/rum-core
```

也可以使用：`pnpm add @arms/rum-core`、`yarn add @arms/rum-core`、`bun add @arms/rum-core`

## README

# @arms/rum-core

ARMS RUM SDK 多端方案的核心抽象层，为各平台 shell（`browser` / `uniapp` / `miniapp` / `minigame` / `electron` / `reactnative` 等）提供统一的角色模型、事件协议与跨运行时工具。

## 角色模型

-   **Client**：装载并编排 `Collector` / `Processor` / `Reporter`，串联事件管线。
-   **Context**：运行时上下文，承载 `config` / `session` / `views` / `emitter` / `identity`。
-   **Shell**：对外 API 入口，提供 `sendCustom` / `sendView` / `sendException` / `sendResource` / `sendAction` / `setUser` 等。
-   **Identity**：业务身份状态机（产品分析），维护登录 / 匿名状态、属性操作折叠、匿名区间回填与 outbox 重发。
-   **ConfigManager**：本地+远端配置编排，支持 `launch-first` / `remote-first` 两种模式。
-   **Collector / Processor / Reporter**：平台扩展点，分别负责数据采集、加工、上报。

事件流：`Collector → sendEvent → Processor 链 → Reporter（队列 / 合并 / 按会话与登录身份分组打包 / 重试） → Transport`。

## Shell 对外 API

| API | 说明 |
| --- | --- |
| `sendCustom(payload)` | 自定义业务事件（`name` / `type` 必填） |
| `sendAction(payload)` | 自定义行为事件（`name` 必填，超 100 字符截断；`group` / `properties` 可选） |
| `sendView(payload)` | 自定义视图性能打点（`type='custom'` 时 `t1` / `t2` / `t3` 至少提供一个） |
| `sendException(payload)` | 异常上报（接受 `RumExceptionEvent | Error`，`source` 默认 `'custom'`） |
| `sendResource(payload)` | 资源 / 请求上报（`name` / `type` / `duration` 必填） |
| `startView(name, options?)` | 手动开启 view（配合 `trackViewsManually`；同名去重，创建新 view 时结束上一个并上报 view 事件） |
| `setUser(user)` | 登录 / 切换用户（`name` + `properties` / `propertiesOnce`） |
| `setUserProperties(props, propertiesOnce?)` / `unsetUserProperties(keys)` | 身份属性补充 / 删除（未登录时暂存，登录时随身份事件一起上报） |
| `reset()` | 退出登录（清除本地身份状态；匿名用户 ID 与当前会话不变） |
| `sendEvent(event, options?)` | 底层事件入口（面向 shell / 高级用法）；`options.immediate` 入队后立即 flush，`options.single` 独立打包上报 |

> `init` 完成前的 `setUser` / `sendAction` 等 Shell 调用会被缓存（上限 50 条），init 完成后按调用顺序回放；身份事件不受会话采样影响（未命中采样的会话仅发送 `identify` 事件）。

## 关键工具（节选）

-   `interceptFunction` / `restoreFunction`：函数拦截支持多订阅共存——重复拦截同一方法仅追加订阅、不再嵌套代理，`restoreFunction` 可按订阅者逐个退订；支持 `isPrototype` 声明回调的 `this` 语义。
-   `parseTracingContext` / `makeTracingHeaders`：多协议 Trace 上下文解析与生成（traceparent / b3 / b3multi / jaeger / sw8），兼容 `Headers` 实例与普通对象、键名大小写不敏感。
-   `parseActionProperties` / `verifyProperties`：埋点属性解析与校验（key ≤ 50 字符、string 值 ≤ 2000 字符、单次 ≤ 20 项；可选 `allowBoolean` 支持布尔值）。

## 支持运行时

浏览器（ES2017+，不含 IE）、Node.js 16+、Deno、Bun、Electron、React Native 0.68+、微信/支付宝/字节小程序（基础库 2.10+ 同等能力）、uni-app 3.x。

`core` 自身不依赖任何浏览器或 Node 专属 API（`window` / `document` / `fetch` / `localStorage` / `XMLHttpRequest` 等）；host API 通过 `env/` 抽象由 shell 注入。

## 开发

```bash
npm run build    # 产出 lib/ (CJS) + es/ (ESM)
npm test         # 单元测试（先 build 后 test，重构后改为直接跑 ts 源码）
```

## 常见问题

### @arms/rum-core 是什么？

朗姆酒 贾瓦斯克花心

### 如何安装 @arms/rum-core？

在项目目录运行 npm install @arms/rum-core，或使用 pnpm add / yarn add / bun add。

### @arms/rum-core 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @arms/rum-core 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @arms/rum-core 可以商用吗？

@arms/rum-core 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @arms/rum-core 的下载量有多少？

根据 npm 官方下载统计，@arms/rum-core 在 2026/10/07 – 2026/11/05 这 30 天内被下载 233,862 次，日均约 7,795 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @arms/rum-core 还在维护吗？

最新版本 0\.1\.12 发布于 2026/10/27（11 天前）；至今共发布 53 个版本，其中过去 12 个月发布了 12 个；首次发布于 2023/11/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。