@grafana/faro-metro-plugin

中文文档
0.5.4发布于 2026/11/06Apache-2.0TypeScriptESM + CJS构建来源已验证近 30 天下载 11.2万

上传回原生( Metro + Hermes) 源地图到法罗源地图 API并注入法罗捆绑 id 序言

中文使用文档
文档目录13 节
  1. 端到端流
  2. 安装
  3. 地铁配置
  4. 环境变量
  5. 当Hermes跳过本地预编译
  6. Hermes 模式
  7. 机器人
  8. 与 @grafana/faro-react-native
  9. 无 @grafana/faro-react-native
  10. iOS 上传
  11. 可选 : sourceMapFile
  12. 卫生检查 : react-native bundle
  13. 格拉法纳大学

法罗源地图 — Metro( 反应原生)

此软件包配置 地铁 因此, 释放与 Grafana 前端可观察性 的工作端到端 :

  1. Bundle id 序言 - 和我想的一样 @grafana/faro-webpack-plugin: JS捆绑套装上方的一小片段 meta.app.bundleId 因此它与源地图记录匹配 @grafana/faro-react-native 编号 : @grafana/faro-web-sdk。 。 。 .

  2. 源地图形状 ——地铁以Hermes预编译表,Hermes解译或JSC等格式发布包装器地图(参见 Hermes 模式) (中文(简体) ).

  3. 上传 - 情况 之后 当地管道生产 编 成 地图( e)hermesc + 键 compose-source-maps.js) (中文(简体) ). 大都会的 没有 上传;由编成的地图是收藏家用于符号的地图.


端到端流

步骤何处
1个安装 @grafana/faro-metro-plugin 并包装 metro.config.js 与 withFaroConfig。 。 。 .
2个安装和备忘 @grafana/faro-react-native 与 不变 app.name 作为 appName 在 Metro 选项中.
3个对于 释放 构建, 导出 FARO_BUNDLE_ID 财务报告和审定财务报表 FARO_SOURCEMAP_* (见 环境变量) (中文(简体) ).
页:1
  • 机器人: 由编成的地图制作后, 上传从 Gradle 运行( 见 机器人) (中文(简体) ).
  • iOS: (英语) 在构成的地图存在后,通过称为此软件包的 Xcode 自动化上传 bin/ 帮助者(仅释放),或手动使用 faro-cli metro upload (见 iOS 上传) (中文(简体) ).

符号运行 法罗收藏器中的服务器侧: 它加载地图 bundleId 从源地图 API 中解析堆栈框架.


安装

npm install --save-dev @grafana/faro-metro-plugin
# or
yarn add --dev @grafana/faro-metro-plugin

还加上 @grafana/faro-react-native 如果使用标准的Android Gradle线条,作为运行时间依赖.


地铁配置

单位 metro.config.js数字 :

const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
const withFaroConfig = require('@grafana/faro-metro-plugin').default;

const faroOpts = {
  appName: 'MyApp',
  endpoint: 'https://your-collector.example.com/api/v1',
  appId: 'your-app-id',
  stackId: 'your-stack-id',
  apiKey: process.env.FARO_SOURCEMAP_API_KEY,
  bundleId: process.env.FARO_BUNDLE_ID,
  verbose: true,
};

module.exports = mergeConfig(getDefaultConfig(__dirname), withFaroConfig({}, faroOpts));

地铁用途 : appName, (中文(简体) ), bundleId (或 FARO_BUNDLE_ID),可选 hermes, (中文(简体) ), sourceMapFile, (中文(简体) ), skipUpload, (中文(简体) ), verbose。 。 。 .
共享选项形状还需要 endpoint, (中文(简体) ), appId, (中文(简体) ), stackId, (中文(简体) ), apiKey; 保持它们与 前端可观察性 – 设置 – 源地图 和与你相同的价值观 faro-cli metro upload 或您的 Gradle / Xcode 自动化.

使用时 @sentry/react-native关闭 外边的哨兵 财务报告和审定财务报表 法罗在里面 因此,序言首先保留,例如:

mergeConfig(getDefaultConfig(__dirname), withSentryConfig(withFaroConfig({}, faroOpts))) 检查哨兵的文档中的RN版本.


环境变量

变量目的
FARO_SOURCEMAP_API_KEY用于上传HTTP请求(Gradle,Xcode自动化,或CLI)的接取符.
FARO_SOURCEMAP_ENDPOINT收集器API基础URL(Gradle,Xcode自动化,或CLI).
FARO_SOURCEMAP_APP_ID上传URL中的App id段(Gradle,Xcode自动化,或CLI).
FARO_SOURCEMAP_STACK_ID用于上传的堆积ID(Gradle,Xcode自动化,或CLI).
FARO_BUNDLE_ID释放 : 平稳的建置id(承诺SHA,CI建置编号. 一定跟大都会公司烤的一样 Omit for local dev. 互联网档案馆的存檔,存档日期2013-10-02..
FARO_SKIP_SOURCEMAP_UPLOAD若为 1 或者说 true, 本地上传步骤在仍然构建时跳过; 序言和地图塑造不变。 在未设定明确标识时,也参与dev捆绑标识行为.
FARO_DISABLE_HERMES_PRECOMPILE稀有. 只有地铁运行时 dev: false 但JS你载 永远 穿过平常的本土 hermesc + 键 compose-source-maps.js 步骤(见 当Hermes跳过本地预编译) (中文(简体) ). 德维 不需要这个- Metro dev: true 自动检测. 常规 安卓/iOS系统 释放 建造必须 离开此未设置。 。 。 .

skipUpload: true, (中文(简体) ), NODE_ENV=development大都会 dev: true,以及 FARO_SKIP_SOURCEMAP_UPLOAD 影响占位符捆绑代号, 以及本地上传步骤是否运行; 没有一个执行从 Metro 上传.

当Hermes跳过本地预编译

设定 FARO_DISABLE_HERMES_PRECOMPILE 只有在以下情况下。 其他人应该 删除 这个.

默认 : 别管了 未设定。该匹配 库存 原生反应:例如Android ./gradlew assembleRelease (或您的项目中运行的等值) bundleReleaseJsAndAssets 和 RN Hermes/地图步骤)和iOS 释放 档案 -- -- 这些管道 永远 预编Hermes字节码并作后地铁地图.

Metro已经选择了正确的映射形状 发展 (单位:千美元)dev: true • Hermes“运行时间”/平整地图)。 没错 没有 需要此变量用于 npx react-native start 或日常调试.

设置变量( 通常只在 CI 或专用脚本中) 何时 全部 下列情况属实:

  1. 你制作一个 生产 与 Metro 捆绑 dev: false (和释放JS捆绑一样).
  2. 那捆绑装入了赫尔墨斯 堆放痕迹的样子 赫尔墨斯 (单位:千美元)line 1 + UTF-8 组合键 字节列 而不是像一张地图 意指的 编 成 她的字节码管道.
  3. 你的输油管 没有 运行标准后Metro hermesc + 键 compose-source-maps.js 流动 assembleRelease / 一个典型的 Xcode 释放构建功能 .

混凝土风格的示例( 说明性, 不是单一的官方命令 ): 团队只运行 npx react-native bundle --platform android --dev false … 在CI, 船舶 index.android.bundle + 键 .map 通过a 自定义 原生外壳或分布路径,以及 永远 引用 Gradle 的释放 Hermes 步骤, 将 Metro 的地图与字节码地图合并 。 生产崩溃,然后表现像 Hermes- on-raw-bundle (英语) 符号; 设置 FARO_DISABLE_HERMES_PRECOMPILE=1 页:1 那个 地铁工作使得所排放的地图符合这些堆栈. 同一个应用程序,用一个 常规 ./gradlew assembleRelease 必须 没有 设置此 - 这样做可以断开 compose-source-maps (这里需要多行包装器地图).

谁设定: 并非每个开发者——只负责维护 非标准 构建定义它一次(例如,在 CI 任务中导出或运行奇异的 Metro 唯一发行捆绑的脚本).


Hermes 模式

Metro输出的形状取决于情景. 插件 永远 在联署材料上方注入法罗捆绑id线 重塑 源图只当引擎报告位于不同的坐标系统中时.

假设插件正在做什么( 普通语言)你最后会怎样
Hermes释放(正常RN)用法罗码标记捆绑; 轻轻地 修正地图, 以免多线断开位置; 留下一个 常规 多行地图,使本土建筑仍能将地铁+赫尔墨斯地图合并.联合来文 与 id + 地图准备就绪 本地语言 Hermes/组成步骤;生产符号通常使用 最终 地图从管道.
Dev, 地铁+赫尔墨斯标记捆绑; 重写 地图,所以 Hermes dev 错误( 一行 + 字节偏移) 仍然可以映射回源 .联合来文 与 编号+ 平地变平 匹配的地图 现场直播 堆叠.
仅限 JSC标记捆绑; 仅限 中间行的变换行号——没有赫尔梅斯特定地图重写.联合来文 与 编号+ 经典 线/栏地图.

我们总是将捆绑贴上标签;当JavaScript引擎报告在不同的坐标系统(Hermes in dev)中崩溃时,我们只“重塑”源地图.

执行(参考): 内部模式名称和触发器 :

模式何时地铁地图形状
precompileddev: false,赫尔墨斯启用(hermes !== false, (中文(简体) ), FARO_DISABLE_HERMES_PRECOMPILE 未设置 - 典型的Android/iOS发布多行地图 +1 生成线路上的行移
runtimedev: true 或者说 FARO_DISABLE_HERMES_PRECOMPILE 设定与UTF-8字节相抵的单行图1号线
jschermes: false 在插件选项中多行地图 +1 换行

对于 precompiled, Xcode/ Gradle 运行 compose-source-maps.js 在地铁之后。 这个步骤需要 多线 包装器地图;在地铁站平整后会打破由编成的地图(sources 空)和象征.

总是上传 之后 作曲:Android上的Gradle,Xcode自动化调用此软件包 bin/ iOS(只释放),或 faro-cli metro upload 你开车上传自己.


机器人

与 @grafana/faro-react-native

  1. 依赖性 : @grafana/faro-react-native (应用)和 @grafana/faro-metro-plugin (编).
  2. 配置地铁为单位 地铁配置。 。 。 .
  3. 导出 FARO_BUNDLE_ID 和所有项目 FARO_SOURCEMAP_* 释放前的 vars 建立.
  4. 运行正常发布工作流程( R)yarn android --mode=release, (中文(简体) ), installRelease, (中文(简体) ), assembleRelease, (中文(简体) ), bundleRelease(中文(简体) ).

反应原生自动链接SDK的Android库. 内容 android/build.gradle 登记册 faroUploadComposedSourceMapAndroidRelease 在你身边 :app 并附上作为 bundleReleaseJsAndAssets 编号 : createBundleReleaseJsAndAssets 之后 gradle.projectsEvaluated。 。 。 .

你个 别 编辑 android/app/build.gradle 这条路.

任务运行 node_modules/@grafana/faro-metro-plugin/bin/faro-upload-source-map.js,引用 faro-cli metro upload 与 --map 指点:

android/app/build/generated/sourcemaps/react/release/index.android.bundle.map

和通过 --bundle-id, (中文(简体) ), --endpoint, (中文(简体) ), --app-id, (中文(简体) ), --stack-id, (中文(简体) ), --api-key 从格拉德环境.

如果shim失踪, 构成的地图不存在, 任何需要的env var失踪, 或 FARO_SKIP_SOURCEMAP_UPLOAD 设置、 任务日志和 跳过 它不会辜负建设.

无 @grafana/faro-react-native

通过应用此软件包的脚本来使用同样的 Gradle 行为 android/app/build.gradle数字 :

apply from: file("../../node_modules/@grafana/faro-metro-plugin/android/source-map-upload.gradle")

调整相对路径,如果您 node_modules 版式不同。 释放前导出与上述相同的内质 vars.


iOS 上传

布局( 和Android 相同 ) : 任何可执行文件都生活在 @grafana/faro-metro-plugin 下级 bin/ (例如,现有的 faro-upload-source-map 输入 faro-cli metro upload) (中文(简体) ). @grafana/faro-react-native 仅应接通 Xcode — 例如反应原生 scriptPhases 钩子.. exec这些路径下 node_modules/@grafana/faro-metro-plugin/bin/不要在SDK内部复制剧本.

只发布 : X码步 必须 禁用非放行配置( 检查 Xcode ) CONFIGURATION / 等同). 调试和面向模拟器的建筑保持安静,永远不要调用上传CLI.

手动 / CI( 当没有为您上传地图时): 如果 自动 路径不运行 - 例如您有 没有 连接到Android Gradle任务或 Xcode 释放 调用脚本阶段 node_modules/@grafana/faro-metro-plugin/bin/,上传步骤被跳过(FARO_SKIP_SOURCEMAP_UPLOAD,缺少env vars),或者CI在工作上构建所构成的地图 无 那些钩子。 调用 faro-cli metro upload 释放后生成 编 成 地图 :

npx faro-cli metro upload \
  --map "$BUILD_DIR/main.jsbundle.map" \
  --endpoint "$FARO_SOURCEMAP_ENDPOINT" \
  --app-id "$FARO_SOURCEMAP_APP_ID" \
  --stack-id "$FARO_SOURCEMAP_STACK_ID" \
  --api-key "$FARO_SOURCEMAP_API_KEY" \
  --bundle-id "$FARO_BUNDLE_ID"

机器人 同样的,只有当Gradle是 没有 已运行上传终端( 或您需要使用 CI 步骤) 不变 标记为 Gradle :

npx faro-cli metro upload \
  --map android/app/build/generated/sourcemaps/react/release/index.android.bundle.map \
  --endpoint "$FARO_SOURCEMAP_ENDPOINT" \
  --app-id "$FARO_SOURCEMAP_APP_ID" \
  --stack-id "$FARO_SOURCEMAP_STACK_ID" \
  --api-key "$FARO_SOURCEMAP_API_KEY" \
  --bundle-id "$FARO_BUNDLE_ID"

旗帜接受匹配 FARO_* 内存倒置,有文件记载 @grafana/faro-cli。 。 。 .

CLI 拒绝地图 空 sources (通常错误的 Metro 映射形状 compose-source-maps.js)和带有代码的退出 3。 。 。 .


可选 : sourceMapFile

Metro 撰写地图 file 字段来自此碱名( 默认) bundle.js) (中文(简体) ). 与 releaseBundleFilename 内 @grafana/faro-react-native 如果你改变它.


卫生检查 : react-native bundle

匹配 appName, (中文(简体) ), FARO_BUNDLE_ID,并用 CI 上传设置.

机器人

npx react-native bundle \
  --platform android \
  --dev false \
  --minify true \
  --entry-file index.js \
  --bundle-output dist/android-release/index.android.bundle \
  --sourcemap-output dist/android-release/index.android.bundle.map \
  --assets-dest dist/android-release/res

iOS系统 - 设定 sourceMapFile 改为 main.jsbundle 因此,地图的运行 file 匹配堆栈和 releaseBundleFilename数字 :

FARO_PLATFORM=ios npx react-native bundle \
  --platform ios \
  --dev false \
  --minify true \
  --entry-file index.js \
  --bundle-output dist/ios-release/main.jsbundle \
  --sourcemap-output dist/ios-release/main.jsbundle.map \
  --assets-dest dist/ios-release/assets

检查 : 套装开始 __faroBundleId_<appName>· ; .map 这是JSON version 3个,不为空 sources, (中文(简体) ), file 匹配您的捆绑底名.


格拉法纳大学

单位 前端可观察性 – 您的应用程序 – 设置打开 来源地图 页:1 endpoint, (中文(简体) ), appId, (中文(简体) ), stackId和面向地铁的片段.

版本与发布记录

@grafana/faro-metro-plugin 共发布 10 个版本,首次发布于 2026/05/20;过去 12 个月发布了 10 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.5.4latest2026/11/0610 天前
0.5.32026/10/2721 天前
0.5.22026/10/151 个月前
0.5.12026/10/061 个月前
0.5.02026/09/221 个月前
0.4.02026/08/292 个月前

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

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

上传回原生( Metro + Hermes) 源地图到法罗源地图 API并注入法罗捆绑 id 序言

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

在项目目录运行 npm install @grafana/faro-metro-plugin,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:metro(>=0.81.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。它还提供命令行工具 faro-upload-source-map,可以用 npx faro-upload-source-map 直接运行。

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

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

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

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

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

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

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

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

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

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