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

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

版本：0\.5\.4
npm 元数据更新时间：2026-11-06T14:18:13.067Z
中文译文更新时间：2026-11-16T21:52:30.442Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：160 kB，12 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：metro \>=0\.81\.0
- 首次发布：2026-05-20T13:13:23.426Z
- 最新版本发布：2026-11-06T14:18:12.427Z
- 近 30 天下载量：111667（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

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

## 安装

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

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

## README

# 法罗源地图 — 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 模式](https://npmcn.com/package/%40grafana/faro-metro-plugin/#readme-hermes-modes)) (中文(简体) ).
    
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_*` (见 [环境变量](https://npmcn.com/package/%40grafana/faro-metro-plugin/#readme-environment-variables)) (中文(简体) ). |
| 页:1 | 
-   **机器人:** 由编成的地图制作后, 上传从 Gradle 运行( 见 [机器人](https://npmcn.com/package/%40grafana/faro-metro-plugin/#readme-android)) (中文(简体) ).
-   **iOS: (英语)** 在构成的地图存在后,通过称为此软件包的 Xcode 自动化上传 `bin/` 帮助者(仅释放),或手动使用 `faro-cli metro upload` (见 [iOS 上传](https://npmcn.com/package/%40grafana/faro-metro-plugin/#readme-ios-upload)) (中文(简体) ).

 |

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

* * *

## 安装

```bash
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`数字 :

```javascript
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跳过本地预编译](https://npmcn.com/package/%40grafana/faro-metro-plugin/#readme-when-hermes-skips-native-precompile)) (中文(简体) ). **德维** 不需要这个- 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)中崩溃时,我们只“重塑”源地图.

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

| 模式 | 何时 | 地铁地图形状 |
| --- | --- | --- |
| `precompiled` | `dev: false`,赫尔墨斯启用(`hermes !== false`, (中文(简体) ), `FARO_DISABLE_HERMES_PRECOMPILE` 未设置 - **典型的Android/iOS发布** | 多行地图 `+1` 生成线路上的行移 |
| `runtime` | `dev: true` **或者说** `FARO_DISABLE_HERMES_PRECOMPILE` 设定 | 与UTF-8字节相抵的单行图1号线 |
| `jsc` | `hermes: 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.  配置地铁为单位 [地铁配置](https://npmcn.com/package/%40grafana/faro-metro-plugin/#readme-metro-configuration)。 。 。 .
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`**数字 :

```groovy
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`** 释放后生成 **编 成** 地图 :

```bash
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 :

```bash
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`](https://npmcn.com/package/%40grafana/faro-cli/README.md#uploading-react-native-metro--hermes-composed-source-maps)。 。 。 .

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 上传设置.

**机器人**

```bash
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`**数字 :

```bash
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 是什么？

上传回原生\( 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 和提交记录判断。

