# @dipakparmar/docusaurus-plugin-umami 中文文档

规范地址：https://npmcn.com/package/%40dipakparmar/docusaurus-plugin-umami/

版本：3\.0\.0
npm 元数据更新时间：2026-07-12T22:31:19.961Z
中文译文更新时间：2026-11-12T10:54:04.652Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40dipakparmar/docusaurus-plugin-umami
原文对照：https://npmcn.com/package/%40dipakparmar/docusaurus-plugin-umami/?lang=original
项目主页：https://github.com/dipakparmar/docusaurus-plugin-umami
源码仓库：https://github.com/dipakparmar/docusaurus-plugin-umami

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

- 包体积（解压后）：29.4 kB，11 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0
- 运行依赖：0 个
- peer 依赖：@docusaurus/utils-validation ^3\.0\.0
- 首次发布：2022-05-31T06:51:38.674Z
- 最新版本发布：2026-07-12T22:31:19.614Z
- 近 30 天下载量：6240（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 2 个）

## 中文简介

Docusaurus的 Umami 分析插件 .

## 安装

```sh
npm install @dipakparmar/docusaurus-plugin-umami
```

也可以使用：`pnpm add @dipakparmar/docusaurus-plugin-umami`、`yarn add @dipakparmar/docusaurus-plugin-umami`、`bun add @dipakparmar/docusaurus-plugin-umami`

## README

# 多龙-插孔-乌米

[Umami 分析](https://umami.is/) 用于 [多龙](https://docusaurus.io/)。 。 。 .

[![Version](https://img.shields.io/npm/v/@dipakparmar/docusaurus-plugin-umami.svg)](https://npmjs.org/package/@dipakparmar/docusaurus-plugin-umami) [![Downloads/week](https://img.shields.io/npm/dw/@dipakparmar/docusaurus-plugin-umami)](https://npmjs.org/package/@dipakparmar/docusaurus-plugin-umami) [![License](https://img.shields.io/npm/l/@dipakparmar/docusaurus-plugin-umami.svg)](https://github.com/dipakparmar/docusaurus-plugin-umami/blob/main/package.json) [![pkg.pr.new](https://pkg.pr.new/badge/dipakparmar/docusaurus-plugin-umami)](https://pkg.pr.new/~/dipakparmar/docusaurus-plugin-umami)

### 仅限生产

这个插件在开发中总是不活跃的,只活跃于生产,以避免污染分析统计.

## 安装

Npm 安装插件 :

```bash
npm install --save @dipakparmar/docusaurus-plugin-umami
```

或带线:

```bash
yarn add @dipakparmar/docusaurus-plugin-umami
```

或带pnm:

```bash
pnpm install @dipakparmar/docusaurus-plugin-umami
```

或带面包:

```bash
bun install @dipakparmar/docusaurus-plugin-umami
```

## 配置

添加插件和网站ID及分析域 `docusaurus.config.js`数字 :

```js
module.exports = {
  plugins: [
    [
      "@dipakparmar/docusaurus-plugin-umami",
      /** @type {import('@dipakparmar/docusaurus-plugin-umami').Options} */
      ({
        websiteID: "your-website-id", // Required
        analyticsDomain: "analytics.mydomain.com", // Required
        scriptName: "script.js", // Optional, defaults to script.js
        dataHostURL: "", // Optional
        dataAutoTrack: true, // Optional, defaults to true
        dataDoNotTrack: false, // Optional, defaults to false
        dataCache: false, // Optional, defaults to false
        dataDomains: "", // Optional, comma separated list of domains, *Recommended*
        dataExcludeSearch: false, // Optional, defaults to false
        dataExcludeHash: false, // Optional, defaults to false
        dataTag: "", // Optional
        dataBeforeSend: "beforeSendHandler", // Optional
        enableRecorder: false, // Optional, defaults to false. Loads recorder.js for session replays & heatmaps
      }),
    ],
  ],
};
```

### 选项

接受字段 :

| 名称 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `websiteID` | `string` | **需求** | 独有的网站ID 从你的Umami分析. |
| `analyticsDomain` | `string` | **需求** | 你负责的Umami分析器所在区域. |
| `scriptName` | `string` | `script.js` | 您的自定义跟踪脚本名称 . |
| `dataHostURL` | `string` |  | 默认情况下, Umami 会将数据发送到脚本所在的地方. 您可以覆盖此数据以发送到另一个位置 . |
| `dataAutoTrack` | `boolean` | `true` | 默认情况下, Umami 自动跟踪所有页面视图和事件 。 您可以使用 tracker 函数禁用此行为并跟踪事件 . |
| `dataDoNotTrack` | `boolean` | `false` | 配置 Umami 以尊重访问者的 Do Not track 设置 . |
| `dataCache` | `boolean` | `false` | 如果从同一个用户那里获得很多页面视图,例如在论坛网站上,可以缓存一些数据来提高跟踪脚本的性能. |
| `dataDomains` | `string` |  | 如果您希望跟踪器只运行在特定域上,可以将其添加到跟踪器脚本中. 这是一个已划定域名的逗号列表. 如果您在中程/ 开发环境中工作, 将会有所帮助 . |
| `dataExcludeSearch` | `boolean` | `false` | 配置跟踪器以不记录URL中的查询参数. |
| `dataExcludeHash` | `boolean` | `false` | 配置跟踪器以不记录 URL 散列 . |
| `dataTag` | `string` |  | 添加一个 [标签](https://docs.umami.is/docs/tags) 到您网站的数据进行分解(例如A/B测试). |
| `dataBeforeSend` | `string` |  | 定义在发送数据前要调用的函数 。 用于在数据发送到服务器前修改数据. |
| `enableRecorder` | `boolean` | `false` | 装入 Umami 的 `recorder.js` 要启用的脚本 [会话重放](https://docs.umami.is/docs/replays) 财务报告和审定财务报表 [热映射](https://docs.umami.is/docs/heatmaps)。其中哪一个被记录在 Umami 仪表板上 切入每个网站. |
| `autoIdentify` | `boolean` | `false` | 指定一个稳定的匿名身份(长期存在于 `localStorage`因此,访问者的会议通过 [身份识别](https://docs.umami.is/docs/distinct-ids)。 。 。 . **见下文隐私说明.** Honors Do Not track / Global 隐私控制 . |
| `autoIdentifyStorageKey` | `string` | `umami.anonymous-id` | `localStorage` 用于坚持 `autoIdentify` 匿名身份证. |

## 自定义事件跟踪

追踪器装入后,即可录入 [自定义事件](https://docs.umami.is/docs/track-events) 两条路.

### 数据属性( 无 JS)

添加 `data-umami-event` (和可选) `data-umami-event-*`对任何要素:

```jsx
<button data-umami-event="Signup" data-umami-event-plan="pro">
  Sign up
</button>
```

### 输入客户端帮助器

从 `/client` 输入一个安全,输入的 API 。 在SSR期间和被推迟的跟踪器脚本装入之前的帮助者没有操作,所以他们可以安全地呼叫任何地方:

```tsx
import {
  track,
  identify,
  useUmami,
} from "@dipakparmar/docusaurus-plugin-umami/client";

// Fire a custom event
track("Signup", { plan: "pro" });

// Assign a distinct id to the session — https://docs.umami.is/docs/distinct-ids
identify({ id: "user@example.com" });

// Inside a React component
function SignupButton() {
  const { track } = useUmami();
  return <button onClick={() => track("Signup", { plan: "pro" })}>Sign up</button>;
}
```

两种方法都在内部运作 `.mdx` 文件 - `data-umami-event` 属性通过,你可以 `import` 文件顶端的帮手。 因为帮助者在服务器侧面渲染时没有操作,因此在Docusaurus提前回复您的页面时,他们可以安全拨打(`useUmami()` 是一个钩子,所以在MDX doc上方或一个组件内部称呼它,而不是有条件的.

> **标记** 通过 `dataTag` 选项 `data-tag` 脚本属性,而不是跟踪 API —— 参见 [Umami 标签](https://docs.umami.is/docs/tags)。 。 。 .

## 匿名会话分组`autoIdentify`(中文(简体) )

设定 `autoIdentify: true` 要让插件在第一次访问时生成随机的ID, 请坚持 `localStorage`,以及 `identify()` 它在每一个负载上——所以一个访客的会话被分组在一起(同一个浏览器=同一个ID). 它的选入和荣誉 Do Not track / Global 隐私控制.

> ⚠️ **隐私.** 持久的识别特征是GDPR/ePrivacy下的个人数据以及一般数据 **需要用户同意** ——使这否定了由美默认的无饼干,无同意的姿态. 使用 `localStorage` 而不是饼干 **没有** 改变这一点;法律待遇相同。 您负责获得必要的同意.
> 
> 同意办法,请假 `autoIdentify` 关闭和呼叫 `identify()` 从 `/client` 在你同意后进入你自己.

## 参考:

-   Docusuarus 插件读取示例 [https://github.com/sgromkov/docusaurus-plugin-yandex-metera (英语)](https://github.com/sgromkov/docusaurus-plugin-yandex-metrica)
-   插件结构 : [https://docusaurus.io/docs/api/plugin-methods#实例](https://docusaurus.io/docs/api/plugin-methods#example)
-   Umami 分析跟踪器配置 : [https://umami.is/docs/tracker-confignation (英语)](https://umami.is/docs/tracker-configuration)

## 常见问题

### @dipakparmar/docusaurus-plugin-umami 是什么？

Docusaurus的 Umami 分析插件 \.

### 如何安装 @dipakparmar/docusaurus-plugin-umami？

在项目目录运行 npm install @dipakparmar/docusaurus-plugin-umami，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@docusaurus/utils-validation（^3\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @dipakparmar/docusaurus-plugin-umami 支持 TypeScript 吗？

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

### @dipakparmar/docusaurus-plugin-umami 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @dipakparmar/docusaurus-plugin-umami 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @dipakparmar/docusaurus-plugin-umami 可以商用吗？

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

### @dipakparmar/docusaurus-plugin-umami 的下载量有多少？

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

### @dipakparmar/docusaurus-plugin-umami 还在维护吗？

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