# @danielgtmn/umami-react 中文文档

规范地址：https://npmcn.com/package/%40danielgtmn/umami-react/

版本：1\.1\.6
npm 元数据更新时间：2026-02-21T19:39:33.124Z
中文译文更新时间：2026-11-11T10:25:13.303Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：22.6 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：0 个
- peer 依赖：react ^18\.2\.0 \|\| ^19\.0\.0，react-dom ^18\.2\.0 \|\| ^19\.0\.0
- 首次发布：2025-03-27T01:51:02.840Z
- 最新版本发布：2026-02-21T19:39:32.997Z
- 近 30 天下载量：2624（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 3 个）

## 中文简介

Umami分析加载器是一个轻量级的脚本,可以方便地将Umami分析集成到你的网站. Umami是一个简单的开放源码网站分析工具,可以提供有价值的洞察力来了解您网站的流量,而无需协商

## 安装

```sh
npm install @danielgtmn/umami-react
```

也可以使用：`pnpm add @danielgtmn/umami-react`、`yarn add @danielgtmn/umami-react`、`bun add @danielgtmn/umami-react`

## README

# 反应 Umami 分析

轻量级反应组件 [Umami 分析](https://umami.is/) ——以隐私为主,开源替代谷歌分析.

零运行时间依赖关系. 完整类型脚本支持 。 与回声18.2+和19.

## 安装

```bash
pnpm add @danielgtmn/umami-react
```

## 快速启动

```tsx
import UmamiAnalytics from '@danielgtmn/umami-react';

function App() {
  return (
    <>
      <UmamiAnalytics
        url="https://analytics.example.com"
        websiteId="your-website-id"
      />
      {/* Your app content */}
    </>
  );
}
```

该组件没有产生任何效果——它只注入了Umami跟踪脚本.

## 道具

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `url` | `string` | `UMAMI_URL` 环境 var | 您的 Umami 实例 URL |
| `websiteId` | `string` | `UMAMI_ID` 环境 var | 您的网站跟踪ID |
| `debug` | `boolean` | `false` | 日志调试信息到控制台 |
| `lazyLoad` | `boolean` | `false` | 在第一次用户交互时装入脚本 |
| `onlyInProduction` | `boolean` | `true` | 开发时跳过加载 |
| `domains` | `string[]` | —— 说 | 仅限于特定域 |
| `scriptAttributes` | `Record<string, string>` | —— 说 | 额外 `<script>` 属性 |

所有道具也可以通过环境变量设置:

```env
UMAMI_URL=https://analytics.example.com
UMAMI_ID=your-website-id
UMAMI_DEBUG=false
UMAMI_LAZY_LOAD=true
```

## 事件跟踪

使用 `useUmami` 自定义事件、页面视图和用户身份的钩子 :

```tsx
import { useUmami } from '@danielgtmn/umami-react';

function MyComponent() {
  const { track, trackPageview, identify } = useUmami();

  return (
    <button onClick={() => track('signup', { plan: 'pro' })}>
      Sign up
    </button>
  );
}
```

### 虎克 API

```tsx
const {
  track,                 // track(eventName, eventData?)
  trackPageview,         // trackPageview(pageviewData?)
  trackPageviewWithUTM,  // trackPageviewWithUTM(utmParams, additionalData?)
  trackPageviewAsync,    // trackPageviewAsync(utmId, fetcherFn, additionalData?)
  identify,              // identify(userId) or identify(sessionData)
} = useUmami();
```

### 带有 UTM 参数的页面视图

```tsx
const { trackPageviewWithUTM } = useUmami();

trackPageviewWithUTM({
  utm_source: 'newsletter',
  utm_medium: 'email',
  utm_campaign: 'spring-sale',
});
```

### Async UTM 获取

在跟踪前从后端获取 UTM 参数 :

```tsx
import { useUmami, UTMFetcher } from '@danielgtmn/umami-react';

const fetchUTM: UTMFetcher = async (utmId) => {
  const res = await fetch(`/api/utm/${utmId}`);
  return res.json();
};

// Fetches UTM data, then tracks the pageview
// Falls back to basic pageview if the fetch fails
await trackPageviewAsync('campaign-123', fetchUTM);
```

### 用户标识

```tsx
const { identify } = useUmami();

// With a string ID
identify('user-123');

// With session data
identify({ userId: 'user-123', plan: 'pro' });

// Both
identify('user-123', { plan: 'pro' });
```

### 禁用自动跟踪

要手动控制页面视图跟踪, 请禁用 Umami 的自动跟踪 :

```tsx
<UmamiAnalytics
  url="https://analytics.example.com"
  websiteId="your-website-id"
  scriptAttributes={{ 'data-auto-track': 'false' }}
/>
```

## 框架实例

### Next.js (App路由器) (英语)

```tsx
// app/layout.tsx
import UmamiAnalytics from '@danielgtmn/umami-react';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <UmamiAnalytics
          url="https://analytics.example.com"
          websiteId="your-website-id"
        />
        {children}
      </body>
    </html>
  );
}
```

### 维特

```tsx
// src/App.tsx
import UmamiAnalytics from '@danielgtmn/umami-react';

function App() {
  return (
    <>
      <UmamiAnalytics
        url="https://analytics.example.com"
        websiteId="your-website-id"
      />
      {/* Your app */}
    </>
  );
}
```

## 类型脚本

所有类型都导出 :

```tsx
import type {
  UmamiAnalyticsProps,
  UmamiConfig,
  PageviewData,
  UTMFetcher,
} from '@danielgtmn/umami-react';
```

## 发展

```bash
pnpm install          # Install dependencies
pnpm dev              # Watch mode
pnpm build            # Production build
pnpm test             # Run tests
pnpm test:coverage    # Tests with coverage
pnpm lint             # Lint
pnpm type-check       # Type check
pnpm size             # Check bundle size
```

承诺跟随 [常规武器委员会](https://conventionalcommits.org/). Git 钩子(Husky)在每次交接前进行打字,打字和测试.

## 捐款

1.  叉出还原
2.  创建您的分支( C)`git checkout -b feat/my-feature`(中文(简体) )
3.  确保所有检查通过(`pnpm test:run && pnpm lint && pnpm type-check`(中文(简体) )
4.  使用常规承诺格式提交
5.  打开拉请求

## 许可证

[麻省理工学院](https://npmcn.com/package/%40danielgtmn/umami-react/LICENSE)

## 常见问题

### @danielgtmn/umami-react 是什么？

Umami分析加载器是一个轻量级的脚本,可以方便地将Umami分析集成到你的网站\. Umami是一个简单的开放源码网站分析工具,可以提供有价值的洞察力来了解您网站的流量,而无需协商

### 如何安装 @danielgtmn/umami-react？

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

### @danielgtmn/umami-react 支持 TypeScript 吗？

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

### @danielgtmn/umami-react 支持 ESM 还是 CommonJS？

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

### @danielgtmn/umami-react 需要什么版本的 Node\.js？

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

### @danielgtmn/umami-react 可以商用吗？

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

### @danielgtmn/umami-react 的下载量有多少？

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

### @danielgtmn/umami-react 还在维护吗？

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