# @grafana/faro-rollup-plugin 中文文档

规范地址：https://npmcn.com/package/%40grafana/faro-rollup-plugin/

版本：0\.13\.2
npm 元数据更新时间：2026-10-15T13:42:31.471Z
中文译文更新时间：2026-11-16T21:43:09.823Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40grafana/faro-rollup-plugin
原文对照：https://npmcn.com/package/%40grafana/faro-rollup-plugin/?lang=original
项目主页：https://github.com/grafana/faro-javascript-bundler-plugins#readme
源码仓库：https://github.com/grafana/faro-javascript-bundler-plugins

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

- 包体积（解压后）：62.1 kB，10 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2024-05-14T18:35:36.009Z
- 最新版本发布：2026-10-15T13:42:31.013Z
- 近 30 天下载量：634785（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：44（近 12 个月 14 个）

## 中文简介

从滚动构建管道上传源图到法罗源图 API

## 安装

```sh
npm install @grafana/faro-rollup-plugin
```

也可以使用：`pnpm add @grafana/faro-rollup-plugin`、`yarn add @grafana/faro-rollup-plugin`、`bun add @grafana/faro-rollup-plugin`

## README

# 法罗源图上传插件 - 滚动/ Vite

此插件将源图上传到法罗采集器,以便在Grafana Cloud Frontend Observation UI中可以去模糊堆栈痕迹.

> \[注\] Faro JavaScript 捆绑插件与客户端提供的应用程序合作。 服务器端渲染尚未支持 .

## 安装

要安装用于 Rollup/Vite 的 Faro JavaScript Bundler 插件,请使用您选择的软件包管理器 .

安装 Rollup/Vite 插件 `npm`,运行 :

```bash
npm install --save-dev @grafana/faro-rollup-plugin
```

安装 Rollup/Vite 插件 `yarn`,运行 :

```bash
yarn add --dev @grafana/faro-rollup-plugin
```

## 使用量

如何使用带有您捆绑器的插件的详情存在于“ 设置” - > “ 来源地图” 选项卡下的前端可观察性插件中, 点击您的乐器应用后即可使用 .

该标签包括Faro JavaScript捆绑插件的必要配置,包括 `appName`, (中文(简体) ), `appId`,以及 `endpoint` 用于插件工作应用的值。 下面提供的细节是关于如何用你的捆绑器使用插件的一般指示.

### 卷起/盘点

要使用 Rollup/Vite 插件,请在您的 `rollup.config.js` 或者说 `vite.config.js`数字 :

```javascript
// other imports
import faroUploader from '@grafana/faro-rollup-plugin';

export default defineConfig(({ mode }) => {
  return {
    // other configs
    plugins: [
      // other plugins
      faroUploader({
        appName: "$your-app-name",
        // this URL is different from the Faro Collector URL - find this value in the Frontend Observability plugin under "Settings" -> "Source Maps" -> "Configure source map uploads"
        endpoint: "$your-faro-sourcemap-api-url",
        apiKey: "$your-api-key",
        appId: "$your-app-id",
        stackId: "$your-stack-id",
        gzipContents: true,
      }),
    ],
  };
```

### 配置选项

Faro JavaScript捆绑插件有下列选项:

-   `appName: string` _所需经费_: 您的应用程序名称 。 这应该符合 `appName` 您在 Faro Web SDK 配置中使用的值.
-   `endpoint: string` _所需经费_: 您的 Faro 收藏器端点的 URL 。 此值位于“ 设置” 下的前端可观察性插件中 - > “ 来源地图 ” - > "配置源地图上传".
-   `apiKey: string` _所需经费_:你的法罗收集器的 API 密钥 。 此值通过创建新范围( 插件和本文"Obtaining API key" 部分提供的细节) 在 grafana.com 上生成.
-   `appId: string` _所需经费_: 您申请的ID 。 这应该符合 `appId` 您在 Faro Web SDK 配置中使用的值.
-   `stackId: string` _所需经费_: 堆栈的ID, 在“ 前端可观察性” 下找到 **设置** - > (中文) **来源地图** - > (中文) **配置源地图上传**
-   `outputFiles: string[] | RegExp` _选项_: 要上传的源映射文件数组或匹配文件的正则gex模式, 默认情况下 Faro 上传所有源映射
-   `bundleId: string` _选项_: 捆绑/建设的ID, 默认自动生成, 或指定一个ID, 在前端可视性中通过捆绑ID过滤
-   `gitHash: string` _选项_: Git 将散列注入捆绑中作为 `window.__faroGitHash_<appName>`。自动通过 `git rev-parse HEAD` 如果没有提供的话。 当 Git 在构建时不可用时, 使用它来提供明确值( 例如, ), `process.env.GITHUB_SHA`) (中文(简体) ). 如果无法解决,则不注射大麻.
-   `keepSourcemaps: boolean` _选项_: 上传后是否将源地图保存在生成的捆绑中, 默认 `false`
-   `gzipContents: boolean` _选项_: 是否在上传前归档并压缩源地图, 默认 `true`
-   `uploadConcurrency: number` _选项_: 单个源图最多上传一次, 默认 `5`。仅适用于下列情况: `gzipContents` 实值 `false`。 。 。 .
-   `verbose: boolean` _选项_: 是否在上传过程中记录动词输出, 默认 `false`
-   `skipUpload: boolean` _选项_: 是否跳过上传源代码地图, 只将 bundId 导出到环境文件, 默认 `false`
-   `maxUploadSize: number` _选项_: 最大上传大小为字节,默认为30MB. 法罗API对单个文件默认上传有30MB的限制. 在特殊情况下,可以通过联系Grafana Cloud支持来改变这一限制.
-   `recursive: boolean` _选项_: 是否循环搜索源地图的子目录, 默认 `false`
-   `proxy: string` _选项_: 用于源地图上传的代理 URL. 支持HTTP和HTTPS的代理. 如果您的代理服务器需要认证, 请在 URL 格式中包含证书 : `http://username:password@proxy.example.com:8080`示例: `http://proxy.example.com:8080` 或者说 `https://user:pass@proxy.example.com:8080`
-   `prefixPath: string` _选项_: 预置到 `file` 源地图中的属性。 当浏览器中的文件出现与捆绑者所意识到的层次不同时,这样做是有用的. 例如,如果使用CDN,堆栈跟踪可能具有从文件路径开始的路径 `cdn/index.js`,但源地图 `file` 属性只显示 `index.js`通过添加 `cdn/` 前缀,源地图解码器可以正确匹配堆栈痕迹与源地图. 实例: `"cdn/"`, (中文(简体) ), `"robo/assets/"`等 (中文(简体) ).
-   `prefixPathBasenameOnly: boolean` _选项_: 当 `true`,从源地图中去除任何目录路径 `file` 支出前财产 `prefixPath`,只保留文件名。 当资产被平地部署到没有子目录结构的CDN时,是有用的. 例如,如果源地图是 `file` 实值 `assets/index.js` 财务报告和审定财务报表 `prefixPath` 实值 `https://cdn.example.com/assets/`,启用此选项生成 `https://cdn.example.com/assets/index.js` 改为 `https://cdn.example.com/assets/assets/index.js`。仅适用于下列情况: `prefixPath` 已经设定。 默认 `false`。 。 。 .

### 将错误链接到执行( 怀疑执行)

插件在构建时将当前 git 输入散列输入您的捆绑 。 法罗Web SDK读取了这个值,并将其包含在每个遥测有效载荷中,使前端可观察性能够将错误与引入错误的承诺联系起来.

分辨率命令 :

1.  明确 `gitHash` 选项
2.  自动检测通过 `git rev-parse HEAD`

**默认( 自动检测)** - 在大多数当地和CI环境中工作 `.git` 目录 :

```javascript
faroUploader({
  // ... required options
  // gitHash is auto-detected from git rev-parse HEAD
});
```

**明确覆盖** - 何时使用 `HEAD` 是合成合并承诺( GitHub 动作) `pull_request` 事件)或 `.git` 无法使用 :

```javascript
faroUploader({
  // ... required options
  gitHash: process.env.GITHUB_SHA,      // GitHub Actions
  // gitHash: process.env.GIT_COMMIT,   // Jenkins
  // gitHash: process.env.CI_COMMIT_SHA, // GitLab CI
});
```

在初始配置后,法罗JavaScript捆绑插件在构建应用程序时会自动上传出您的源地图给Grafana Cloud. 您可以在“ 设置” - > 前端可观察性插件中的“ 源地图” 标签中验证源地图成功上传 。 从那里可以看到您上传的源地图 .

完成所有所需步骤后, 您已完成 - 法罗收集器开始处理您的源地图, 并将其与您的遥测数据连接 。 上传到 Faro 收藏器的源地图的堆栈痕迹部分在查看您错误数据时会自动去模糊并显示在前端可观察性插件中 .

## 常见问题

### @grafana/faro-rollup-plugin 是什么？

从滚动构建管道上传源图到法罗源图 API

### 如何安装 @grafana/faro-rollup-plugin？

在项目目录运行 npm install @grafana/faro-rollup-plugin，或使用 pnpm add / yarn add / bun add。

### @grafana/faro-rollup-plugin 支持 TypeScript 吗？

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

### @grafana/faro-rollup-plugin 支持 ESM 还是 CommonJS？

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

### @grafana/faro-rollup-plugin 可以商用吗？

@grafana/faro-rollup-plugin 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @grafana/faro-rollup-plugin 的下载量有多少？

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

### @grafana/faro-rollup-plugin 还在维护吗？

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

