@grafana/faro-webpack-plugin

中文文档
0.14.2发布于 2026/10/15Apache-2.0TypeScriptESM + CJS构建来源已验证近 30 天下载 17.9万

从 Webpack 构建管道上传到 Faro 源地图 API

中文使用文档
文档目录4 节
  1. 安装
  2. 使用量
  3. 配置选项
  4. 将错误链接到执行( 怀疑执行)

法罗源图上传插件 - Webpack

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

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

安装

要为 Webpack 安装 Faro JavaScript 捆绑插件,请使用您选择的软件包管理器.

npm install --save-dev @grafana/faro-webpack-plugin

安装 Webpack 插件 yarn,运行 :

yarn add --dev @grafana/faro-webpack-plugin

使用量

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

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

要使用 Webpack 插件,请在您的 webpack.config.js数字 :

// other imports
import FaroSourceMapUploaderPlugin from "@grafana/faro-webpack-plugin";

module.exports = {
  // other configs
  plugins: [
    // other plugins
    new FaroSourceMapUploaderPlugin({
      appName: "$your-app-name",
      endpoint: "$your-faro-collector-url",
      apiKey: "$your-api-key",
      appId: "$your-app-id",
      stackId: "$your-stack-id",
      gzipContents: true,
    }),
  ],
};

使用代理服务器

如果您需要通过代理服务器路径源地图上传, 您可以使用 proxy 选项 :

new FaroSourceMapUploaderPlugin({
  appName: "$your-app-name",
  endpoint: "$your-faro-collector-url",
  apiKey: "$your-api-key",
  appId: "$your-app-id",
  stackId: "$your-stack-id",
  proxy: "http://proxy.example.com:8080",
  gzipContents: true,
}),

如果您的代理机需要认证, 请在 URL 中包含证书 :

new FaroSourceMapUploaderPlugin({
  // ... other options
  proxy: "http://username:[email protected]:8080",
}),

配置选项

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

  • appName: string 所需经费: 您的应用程序名称, 它应该符合 appName 在您的 Faro Web SDK 配置中使用的值
  • endpoint: string 所需经费: 您的 Faro Collectionor 端点的 URL, 在前端可观察性中找到 设置 财务报告和审定财务报表 网络 SDK 配置
  • apiKey: string 所需经费: 用于您的 Faro Collectionor 的 API 密钥, 您可以在 [grafana.com] 上生成一个新的范围, 指的是 获取 API 密钥 节
  • appId: string 所需经费: 您申请的ID, 它应该符合 appId 在您的 Faro Web SDK 配置中使用的值
  • stackId: string 所需经费: 堆栈的ID, 在“ 前端可观察性” 下找到 设置 - > (中文) 来源地图 - > (中文) 配置源地图上传
  • outputPath: string 选项: 覆盖源地图所在的输出目录路径,默认使用Webpack的输出. 路径
  • 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:[email protected]:8080示例: http://proxy.example.com:8080 或者说 https://user:[email protected]:8080
  • prefixPath: string 选项: 预置到 file 源地图中的属性。 当浏览器中的文件出现与捆绑者所意识到的层次不同时,这样做是有用的. 例如,如果使用CDN,堆栈跟踪可能具有从文件路径开始的路径 cdn/index.js,但源地图 file 属性只显示 index.js通过添加 cdn/ 前缀,源地图解码器可以正确匹配堆栈痕迹与源地图. 如果两者兼有 prefixPath 财务报告和审定财务报表 nextjs 将合并为 ${prefixPath}/_next/实例: "cdn/", (中文(简体) ), "robo/assets/", (中文(简体) ), "_next/"
  • 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。 。 。 .
  • nextjs: boolean 选项: 是否预选 _next/ 为 Next.js 兼容性创建源地图文件属性。 只有当您的 NextJS 应用程序同时拥有客户端和服务器侧码时才需要此功能 。 如果您的应用程序只是客户端, 不需要这样做 。 默认 false如果两者兼而有之 prefixPath 财务报告和审定财务报表 nextjs 将合并为 ${prefixPath}/_next/

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

分辨率命令 :

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

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

new FaroSourceMapUploaderPlugin({
  // ... required options
  // gitHash is auto-detected from git rev-parse HEAD
});

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

new FaroSourceMapUploaderPlugin({
  // ... 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-webpack-plugin 共发布 46 个版本,首次发布于 2024/05/15;过去 12 个月发布了 15 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.14.2latest2026/10/151 个月前
0.14.12026/10/061 个月前
0.14.02026/09/221 个月前
0.13.02026/08/292 个月前
0.12.12026/07/074 个月前
0.12.02026/06/025 个月前

关于 @grafana/faro-webpack-plugin 的常见问题

@grafana/faro-webpack-plugin 是什么?

从 Webpack 构建管道上传到 Faro 源地图 API

如何安装 @grafana/faro-webpack-plugin?

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

@grafana/faro-webpack-plugin 支持 TypeScript 吗?

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

@grafana/faro-webpack-plugin 支持 ESM 还是 CommonJS?

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

@grafana/faro-webpack-plugin 可以商用吗?

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

@grafana/faro-webpack-plugin 的下载量有多少?

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

@grafana/faro-webpack-plugin 还在维护吗?

最新版本 0.14.2 发布于 2026/10/15(1 个月前);至今共发布 46 个版本,其中过去 12 个月发布了 15 个;首次发布于 2024/05/15。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。