# @analytics/segment 中文文档

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

版本：2\.1\.0
npm 元数据更新时间：2023-12-31T16:51:41.660Z
中文译文更新时间：2026-11-06T01:52:11.722Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：65.6 kB，10 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：未声明
- 运行依赖：1 个
- 首次发布：2019-10-07T05:59:36.494Z
- 最新版本发布：2023-12-31T16:51:41.484Z
- 近 30 天下载量：282879（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 0 个）

## 中文简介

浏览器节点“ 分析” 模块的片段集成( C)

## 安装

```sh
npm install @analytics/segment
```

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

## README

# 部件插件 `analytics`

与 [部分](https://segment.com/) 页:1 [分析](https://www.npmjs.com/package/analytics)

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

单击以扩展

-   [安装](https://npmcn.com/package/%40analytics/segment/#readme-installation)
-   [如何使用](https://npmcn.com/package/%40analytics/segment/#readme-how-to-use)
-   [支持的平台](https://npmcn.com/package/%40analytics/segment/#readme-platforms-supported)
-   [浏览器使用量](https://npmcn.com/package/%40analytics/segment/#readme-browser-usage)
    -   [浏览器 API](https://npmcn.com/package/%40analytics/segment/#readme-browser-api)
    -   [浏览器配置选项](https://npmcn.com/package/%40analytics/segment/#readme-configuration-options-for-browser)
-   [服务器侧用法](https://npmcn.com/package/%40analytics/segment/#readme-server-side-usage)
    -   [服务器侧 API](https://npmcn.com/package/%40analytics/segment/#readme-server-side-api)
    -   [服务器侧配置选项](https://npmcn.com/package/%40analytics/segment/#readme-configuration-options-for-server-side)
-   [其他例子](https://npmcn.com/package/%40analytics/segment/#readme-additional-examples)
-   [自定义页面名称字段](https://npmcn.com/package/%40analytics/segment/#readme-customing-the-page-name-field)
-   [从自定义代理机装入脚本](https://npmcn.com/package/%40analytics/segment/#readme-loading-script-from-custom-proxy)
-   [组织电话](https://npmcn.com/package/%40analytics/segment/#readme-making-group-calls)
    -   [浏览器示例](https://npmcn.com/package/%40analytics/segment/#readme-browser-example)
    -   [服务器侧示例](https://npmcn.com/package/%40analytics/segment/#readme-server-side-example)

## 安装

```bash
npm install analytics
npm install @analytics/segment
```

## 如何使用

这个 `@analytics/segment` 软件包在 [浏览器](https://npmcn.com/package/%40analytics/segment/#readme-browser-usage) 财务报告和审定财务报表 [在节点.js的服务器侧](https://npmcn.com/package/%40analytics/segment/#readme-server-side-usage)。要使用、安装软件包,在您的工程中包含并初始化插件 [分析](https://www.npmjs.com/package/analytics)。 。 。 .

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

```js
import Analytics from 'analytics'
import segmentPlugin from '@analytics/segment'

const analytics = Analytics({
  app: 'awesome-app',
  plugins: [
    segmentPlugin({
      writeKey: '123-xyz'
    })
  ]
})

/* 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` 与 `segmentPlugin` 插件, 数据将随时发送到片段 [分析. p](https://getanalytics.io/api/#analyticspage), (中文(简体) ), [分析. track](https://getanalytics.io/api/#analyticstrack),或 [分析 识别](https://getanalytics.io/api/#analyticsidentify) 被调用.

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

## 支持的平台

这个 `@analytics/segment` 软件包在 [浏览器](https://npmcn.com/package/%40analytics/segment/#readme-browser-usage) 财务报告和审定财务报表 [在节点.js的服务器侧](https://npmcn.com/package/%40analytics/segment/#readme-server-side-usage)

## 浏览器使用量

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

-   **[分析. p](https://getanalytics.io/api/#analyticspage)** - 将页面视图发送到部分
-   **[分析. track](https://getanalytics.io/api/#analyticstrack)** - 跟踪自定义事件并发送到片段
-   **[分析 识别](https://getanalytics.io/api/#analyticsidentify)** - 确定访客身份,并将详情发送给分部
-   **[分析. 重置](https://getanalytics.io/api/#analyticsreset)** - 为分块值重置浏览器存储 cookie 和本地存储器

### 浏览器 API

```js
import Analytics from 'analytics'
import segmentPlugin from '@analytics/segment'

const analytics = Analytics({
  app: 'awesome-app',
  plugins: [
    segmentPlugin({
      writeKey: '123-xyz'
    })
  ]
})

```

### 浏览器配置选项

| 选项 | 说明 |
| :-- | :-- |
| `writeKey`  
**所需经费** - 绳子 | 您的部分写入关键 |
| `disableAnonymousTraffic`  
_选项_ - 布尔 | 禁用匿名访客的加载段 |
| `customScriptSrc`  
_选项_ - 布尔 | 覆盖段片断 URL, 用于通过自定义的 CDN 代理加载 |
| `integrations`  
_选项_ - 对象 | 启用/ 残疾部分目的地 [https://bit.ly/38nRBj3 页面存档备份,存于互联网档案馆](https://bit.ly/38nRBj3) |

## 服务器侧用法

段服务器侧节点.js插件使用这些分析的 api 方法:

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

### 服务器侧 API

```js
import Analytics from 'analytics'
import segmentPlugin from '@analytics/segment'

const analytics = Analytics({
  app: 'awesome-app',
  plugins: [
    segmentPlugin({
      writeKey: '123-xyz'
    })
  ]
})

```

### 服务器侧配置选项

| 选项 | 说明 |
| :-- | :-- |
| `writeKey`  
**所需经费** - 绳子 | 与您的 Session.io 项目相对应的密钥 |
| `disableAnonymousTraffic`  
_选项_ - 布尔 | 禁用匿名访客的加载段 |
| `host`  
_选项_ - 绳子 | API的基础URL. 默认:"https://api.segment.io" |
| `path`  
_选项_ - 绳子 | API路径. 默认 : "/v1/ batch" |
| `maxRetries`  
_选项_ - 数目 | 重试冲出批次的次数 。 默认: 3 |
| `maxEventsInBatch`  
_选项_ - 数目 | 冲洗前要排队的消息数 。 默认: 15 |
| `flushInterval`  
_选项_ - 数目 | 自动冲出队列前需要等待的毫秒数 。 默认: 10000 |
| `httpRequestTimeout`  
_选项_ - 数目 | 等待 http 请求的最大毫秒数 。 默认: 10000 |
| `disable`  
_选项_ - 布尔 | 禁用分析库 。 所有电话都会是无谓的 默认:虚假. |
| `httpClient`  
_选项_ - HTTPFetchFn (美国英语) | 提供默认 http 客户端执行 |

## 其他例子

以下是其他执行实例.

服务器侧 ES6

```js
import Analytics from 'analytics'
import segmentPlugin from '@analytics/segment'

const analytics = Analytics({
  app: 'awesome-app',
  plugins: [
    segmentPlugin({
      writeKey: '123-xyz'
    })
    // ...other 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'
})

```

具有共同JS的服务器端节点.js

如果使用节点,您将想要导入 `.default`

```js
const analyticsLib = require('analytics').default
const segmentPlugin = require('@analytics/segment').default

const analytics = analyticsLib({
  app: 'my-app-name',
  plugins: [
    segmentPlugin({
      writeKey: '123-xyz'
    })
  ]
})

/* 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'
})

```

在 HTML 中使用

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

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

      /* 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/segment` 在无害环境管理模块中.

```html
<!DOCTYPE html>
<html>
  <head>
    <title>Using @analytics/segment 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 analyticsSegment from 'https://unpkg.com/@analytics/segment/lib/analytics-plugin-segment.browser.es.js?module'
      /* Initialize analytics */
      const Analytics = analytics({
        app: 'analytics-html-demo',
        debug: true,
        plugins: [
          analyticsSegment({
            writeKey: '123-xyz'
          })
          // ... 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>

```

## 自定义页面名称字段

默认情况下,页面名称是 `document.title` 数值.

使用更短的名字

```js
analytics.page({
  name: 'HomePage'
})
```

这会很快变得很棘手,我们建议不要这样.

## 从自定义代理机装入脚本

在特定情况下,您可能想要从不同的URL中加载您自己版本的片段分析.

要做到这一点,你可以添加 `customScriptSrc` 选项指向您的自定义段脚本.

```js
import Analytics from 'analytics'
import segmentPlugin from '@analytics/segment'

const analytics = Analytics({
  app: 'awesome-app',
  plugins: [
    segmentPlugin({
      writeKey: '123-xyz',
      // Load segment's analytics.js from somewhere else
      customScriptSrc: 'https://yoursite.com/my-custom-loader.js'
    })
  ]
})
```

## 组织电话

这个 `.group` 调用是专为部分的,分析器的 lib 默认不会暴露这一点。 但你很幸运,谢谢 [自定义方法](https://getanalytics.io/plugins/writing-plugins/#adding-custom-methods) 打开插件!

发送一个组呼叫到 Spart 运行 `analytics.plugins.segment.group()` 定制方法.

这个 `analytics.plugins.segment.group` 函数的签名如下:

```js
analytics.group(groupId, [traits], [options], [callback]);
```

### 浏览器示例

```js
import Analytics from 'analytics'
import segmentPlugin from '@analytics/segment'

// Initialize analytics instance with plugins
const analytics = Analytics({
  app: 'your-app-name',
  plugins: [
    segmentPlugin({
      writeKey: '123-xyz'
    }),
  ]
})

// Usage:
// Now you can call segment.group in your app like so
analytics.plugins.segment.group('Group ID XYZ', {
  principles: ['Bill', 'Bob'],
  site: 'Apple co',
  statedGoals: 'Do awesome stuff',
  industry: 'Technology'
})
```

### 服务器侧示例

```js
const analyticsLib = require('analytics').default
const segmentPlugin = require('@analytics/segment')

// Initialize analytics instance with plugins
const analytics = Analytics({
  app: 'your-app-name',
  plugins: [
    segmentPlugin({
      writeKey: '123-xyz'
    }),
  ]
})

analytics.plugins.segment.group('Group ID XYZ', {
  principles: ['Bill', 'Bob'],
  site: 'Apple co',
  statedGoals: 'Do awesome stuff',
  industry: 'Technology'
})
```

## 常见问题

### @analytics/segment 是什么？

浏览器节点“ 分析” 模块的片段集成\( C\)

### 如何安装 @analytics/segment？

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

### @analytics/segment 支持 TypeScript 吗？

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

### @analytics/segment 支持 ESM 还是 CommonJS？

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

### @analytics/segment 可以商用吗？

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

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

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

### @analytics/segment 还在维护吗？

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