# @analytics/google-analytics 中文文档

规范地址：https://npmcn.com/package/%40analytics/google-analytics/

版本：1\.1\.0
npm 元数据更新时间：2024-12-11T22:08:47.238Z
中文译文更新时间：2026-11-06T01:51:53.988Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：70.8 kB，10 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2019-09-30T00:36:20.452Z
- 最新版本发布：2024-12-11T22:08:47.020Z
- 近 30 天下载量：347665（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 0 个）

## 中文简介

用于“ 分析” 模块的 Google 分析 v4 插件

## 安装

```sh
npm install @analytics/google-analytics
```

也可以使用：`pnpm add @analytics/google-analytics`、`yarn add @analytics/google-analytics`、`bun add @analytics/google-analytics`

## README

# 谷歌分析

此分析插件会将 google 分析 v. 4 载入您的应用程序 .

详情 [见文件](https://getanalytics.io/plugins/google-analytics/)。 。 。 .

单击以扩展

-   [安装](https://npmcn.com/package/%40analytics/google-analytics/#readme-installation)
-   [如何使用](https://npmcn.com/package/%40analytics/google-analytics/#readme-how-to-use)
-   [支持的平台](https://npmcn.com/package/%40analytics/google-analytics/#readme-platforms-supported)
-   [浏览器使用量](https://npmcn.com/package/%40analytics/google-analytics/#readme-browser-usage)
    -   [浏览器 API](https://npmcn.com/package/%40analytics/google-analytics/#readme-browser-api)
    -   [浏览器配置选项](https://npmcn.com/package/%40analytics/google-analytics/#readme-configuration-options-for-browser)
-   [其他例子](https://npmcn.com/package/%40analytics/google-analytics/#readme-additional-examples)
-   [修复"双页浏览"](https://npmcn.com/package/%40analytics/google-analytics/#readme-fix-double-page-views)
-   [谷歌分析 v3](https://npmcn.com/package/%40analytics/google-analytics/#readme-legacy-google-analytics-v3)
-   [一起使用GA3和GA4](https://npmcn.com/package/%40analytics/google-analytics/#readme-using-ga3-and-ga4-together)

## 安装

```bash
npm install analytics
npm install @analytics/google-analytics
```

## 如何使用

这个 `@analytics/google-analytics` 软件包在 [浏览器](https://npmcn.com/package/%40analytics/google-analytics/#readme-browser-usage)。要使用、安装软件包,在您的工程中包含并初始化插件 [分析](https://www.npmjs.com/package/analytics)。 。 。 .

以下为如何使用浏览器插件的例子.

```js
import Analytics from 'analytics'
import googleAnalytics from '@analytics/google-analytics'

const analytics = Analytics({
  app: 'awesome-app',
  plugins: [
    googleAnalytics({
      measurementIds: ['G-abc123']
    })
  ]
})

/* Track a page view */
analytics.page()

/* Track a custom event */
analytics.track('cartCheckout', {
  item: 'pink socks',
  price: 20
})

/* Identify a visitor */
analytics.identify('user-id-xyz', {
  firstName: 'bill',
  lastName: 'murray'
})

```

初始化后 `analytics` 与 `googleAnalytics` 插件, 数据将发送到 Google 分析器 [分析 识别](https://getanalytics.io/api/#analyticsidentify), (中文(简体) ), [分析. p](https://getanalytics.io/api/#analyticspage),或 [分析. track](https://getanalytics.io/api/#analyticstrack) 被调用.

见 [其他执行实例](https://npmcn.com/package/%40analytics/google-analytics/#readme-additional-examples) 在您的项目中使用更多细节 .

## 支持的平台

这个 `@analytics/google-analytics` 软件包在 [浏览器](https://npmcn.com/package/%40analytics/google-analytics/#readme-browser-usage)

## 浏览器使用量

Google Analytics客户端浏览器插件使用这些分析的api方法:

-   **[分析 识别](https://getanalytics.io/api/#analyticsidentify)** - 确定访客身份,并将详情发送给谷歌分析公司
-   **[分析. p](https://getanalytics.io/api/#analyticspage)** - 将页面视图输入谷歌分析
-   **[分析. track](https://getanalytics.io/api/#analyticstrack)** - 追踪自定义事件并发送到谷歌分析

### 浏览器 API

```js
import Analytics from 'analytics'
import googleAnalytics from '@analytics/google-analytics'

const analytics = Analytics({
  app: 'awesome-app',
  plugins: [
    googleAnalytics({
      measurementIds: ['G-abc123']
    })
  ]
})

```

### 浏览器配置选项

| 选项 | 说明 |
| :-- | :-- |
| `measurementIds`  
**所需经费** - 阵列. | Google 分析计量标识 |
| `debug`  
_选项_ - 布尔 | 启用 Google 分析调试模式 |
| `dataLayerName`  
_选项_ - 绳子 | 数据Layer对象的可选名称。 默认为 ga4DataLayer . |
| `gtagName`  
_选项_ - 绳子 | 数据Layer对象的可选名称。 默认为 `gtag`。 。 。 . |
| `gtagConfig.anonymize_ip`  
_选项_ - 布尔 | 启用 [IP地址匿名化](https://bit.ly/3c660Rd) 发送到谷歌分析. |
| `gtagConfig.cookie_domain`  
_选项_ - 对象 | 配置时的额外 cookie 属性 [饼干](https://developers.google.com/analytics/devguides/collection/analyticsjs/cookies-user-id#configuring_cookie_field_settings) |
| `gtagConfig.cookie_expires`  
_选项_ - 对象 | 配置时的额外 cookie 属性 [饼干](https://developers.google.com/analytics/devguides/collection/analyticsjs/cookies-user-id#configuring_cookie_field_settings) |
| `gtagConfig.cookie_prefix`  
_选项_ - 对象 | 配置时的额外 cookie 属性 [饼干](https://developers.google.com/analytics/devguides/collection/analyticsjs/cookies-user-id#configuring_cookie_field_settings) |
| `gtagConfig.cookie_update`  
_选项_ - 对象 | 配置时的额外 cookie 属性 [饼干](https://developers.google.com/analytics/devguides/collection/analyticsjs/cookies-user-id#configuring_cookie_field_settings) |
| `gtagConfig.cookie_flags`  
_选项_ - 对象 | 配置时的额外 cookie 属性 [饼干](https://developers.google.com/analytics/devguides/collection/analyticsjs/cookies-user-id#configuring_cookie_field_settings) |
| `customScriptSrc`  
_选项_ - 绳子 | 如果代理调用, 自定义谷歌分析脚本的 URL |
| `nonce`  
_选项_ - 绳子 | 内容-安全政策非现金价值 |

## 其他例子

以下是其他执行实例.

在 HTML 中使用

以下是通过unpkg CDN导入的例子. 请注意,这将拉入该套件的最新版本.

```html
<!DOCTYPE html>
<html>
  <head>
    <title>Using @analytics/google-analytics in HTML</title>
    <script src="https://unpkg.com/analytics/dist/analytics.min.js"></script>
    <script src="https://unpkg.com/@analytics/google-analytics/dist/@analytics/google-analytics.min.js"></script>
    <script type="text/javascript">
      /* Initialize analytics */
      var Analytics = _analytics.init({
        app: 'my-app-name',
        plugins: [
          analyticsGa.init({
            measurementIds: ['G-abc123']
          })
        ]
      })

      /* Track a page view */
      analytics.page()

      /* Track a custom event */
      analytics.track('cartCheckout', {
        item: 'pink socks',
        price: 20
      })

      /* Identify a visitor */
      analytics.identify('user-id-xyz', {
        firstName: 'bill',
        lastName: 'murray'
      })
    </script>
  </head>
  <body>
    ....
  </body>
</html>

```

通过 ES 模块在 HTML 中使用

使用 `@analytics/google-analytics` 在无害环境管理模块中.

```html
<!DOCTYPE html>
<html>
  <head>
    <title>Using @analytics/google-analytics in HTML via ESModules</title>
    <script>
      // Polyfill process.
      // **Note**: Because `import`s are hoisted, we need a separate, prior <script> block.
      window.process = window.process || { env: { NODE_ENV: 'production' } }
    </script>
    <script type="module">
      import analytics from 'https://unpkg.com/analytics/lib/analytics.browser.es.js?module'
      import analyticsGa from 'https://unpkg.com/@analytics/google-analytics/lib/analytics-plugin-ga.browser.es.js?module'
      /* Initialize analytics */
      const Analytics = analytics({
        app: 'analytics-html-demo',
        debug: true,
        plugins: [
          analyticsGa({
            measurementIds: ['G-abc123']
          })
          // ... add any other third party analytics plugins
        ]
      })

      /* Track a page view */
      analytics.page()

      /* Track a custom event */
      analytics.track('cartCheckout', {
        item: 'pink socks',
        price: 20
      })

      /* Identify a visitor */
      analytics.identify('user-id-xyz', {
        firstName: 'bill',
        lastName: 'murray'
      })
    </script>
  </head>
  <body>
    ....
  </body>
</html>

```

## 修复"双页浏览"

Google analytics 4有时会自动为单页应用程序发送页面视图. 要禁用此选项, 您需要进入您的流的设置, 点击“ 增强度量” 部分, 并取消检查“ 根据浏览器历史事件更改 ” 设置 。 这只能确保 `analytics.page()` 电话将发送页面浏览到 Google 分析 v4.

![disable-auto-spa-pageviews](https://user-images.githubusercontent.com/532272/180305960-b6172469-f3ee-4d48-85fd-3c4d0a07e777.png)

## 谷歌分析 v3

有关谷歌分析的更古老版本,请参见: [`@analytics/google-analytics-v3` 软件包](https://www.npmjs.com/package/@analytics/google-analytics-v3) 或 [GA3 插件文件](https://getanalytics.io/plugins/google-analytics-v3/)

## 一起使用GA3和GA4

如下所示,可以同时使用GA3和GA4。 记住GA3 从2023年7月开始 将会贬值

```js
import Analytics from 'analytics'
import googleAnalyticsPlugin from '@analytics/google-analytics'
import googleAnalyticsV3Plugin from '@analytics/google-analytics-v3'

/* Initialize analytics instance */
const analytics = Analytics({
  app: 'my-app',
  plugins: [
    /* Load Google Analytics v4 */
    googleAnalyticsPlugin({
      measurementIds: ['G-abc123'],
    }),
    /* Load Google Analytics v3 */
    googleAnalyticsV3Plugin({
      trackingId: 'UA-11111111-2',
    }),
  ],
})

analytics.page()
```

## 常见问题

### @analytics/google-analytics 是什么？

用于“ 分析” 模块的 Google 分析 v4 插件

### 如何安装 @analytics/google-analytics？

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

### @analytics/google-analytics 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/analytics\_\_google-analytics 是否存在。

### @analytics/google-analytics 支持 ESM 还是 CommonJS？

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

### @analytics/google-analytics 可以商用吗？

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

### @analytics/google-analytics 的下载量有多少？

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

### @analytics/google-analytics 还在维护吗？

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