# @grafana/faro-cli 中文文档

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

版本：0\.13\.4
npm 元数据更新时间：2026-11-06T14:17:07.187Z
中文译文更新时间：2026-11-16T21:44:34.188Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：331 kB，13 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：5 个
- 首次发布：2025-03-14T15:54:50.746Z
- 最新版本发布：2026-11-06T14:17:06.759Z
- 近 30 天下载量：465426（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：29（近 12 个月 19 个）

## 中文简介

用于上传源图到 Faro 源图 API 的 CLI

## 安装

```sh
npm install @grafana/faro-cli
```

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

## README

# 法罗CLI

用于将源地图上传到使用cURL的法罗源地图API的命令行界面.

## 安装

```bash
npm install --save-dev @grafana/faro-cli
```

或者说

```bash
yarn add --dev @grafana/faro-cli
```

## 所需资源

-   cURL 必须在您的系统中安装,并在您的路径中可用 .

## 使用量

### 上传源代码地图

CLI使用头罩下方的cURL将源图上传到法罗API.

**网页( Webpack / Vite / 滚动 / Rspack) :**

```bash
npx faro-cli upload \
  --endpoint "your-faro-sourcemap-api-url" \
  --app-id "your-app-id" \
  --api-key "your-api-key" \
  --stack-id "your-stack-id" \
  --bundle-id "your-bundle-id" \
  --output-path "./dist" \
  --verbose
```

对 CI , 设定 `FARO_SOURCEMAP_API_KEY` 在环境中,并省略 `--api-key`. 明确旗帜在两种旗帜设置时优先.

**原生反应( Metro) :**

```bash
npx faro-cli metro upload \
  --map "path/to/your.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" \
  --verbose
```

两个命令只有不同 **他们是如何发现地图上传的**数字 :

-   `upload` (web)通过 `--output-path` 逐一扫描 `.map` 文档。 你不列举路径 也不担心嵌入式文件夹.
-   `metro upload` (反应原生)一个 `.map` 路径通过 `--map`. CLI从未从此路径本身得到——呼叫者(Gradle hook,Xcode后构建脚本,手动引用)负责指向正确的文件. `--bundle-id` (或 `FARO_BUNDLE_ID`)必须匹配任何id `@grafana/faro-metro-plugin` 被烤入运出JS的包里 所以上传的地图密钥 到了法罗的运行时间遥测。 见 [`@grafana/faro-metro-plugin` 读取](https://npmcn.com/package/%40grafana/faro-metro-plugin/README.md) 用来传递哪个平台的地图.

两个命令在每次飞行前都做同样的轻量级飞行 `.map` 上传前: 将其解析为 JSON, 验证它是一个 v3 源地图, 并( 与下游符号相容 ) 回写 `file` 属性,如果缺少。 他们从来不碰 `mappings`, (中文(简体) ), `sources`,或 `sourcesContent` 字段。 见 [连接设置优先](https://npmcn.com/package/%40grafana/faro-cli/#readme-connection-settings-precedence) 财务报告和审定财务报表 [验证和退出代码](https://npmcn.com/package/%40grafana/faro-cli/#readme-validation-and-exit-codes) 整个合同.

#### 文件大小限制

法罗API对单个文件默认上传有30MB的限制. 这个限制适用于文件的未压缩大小,无论在传输过程中是否使用压缩. CLI 通过:

1.  上传前正在检查文件大小
2.  关于超过限制的文件的警告
3.  跳过太大的文件
4.  以流媒体方式处理文件, 累积文件直至达到大小限制后再上传每批文件

这种流出方式是捆绑插件使用的同一种方法,确保所有上传方法的行为一致. CLI智能地逐一处理文件,在达到大小限制时上传批次,在保持API大小限制的同时优化上传过程.

虽然 `--gzip-payload` 选项可以显著地减少网络传输大小,原始未压缩文件大小仍然必须在配置的大小限制下才能被API接受.

您可以使用 `--max-upload-size` 选项,允许您在字节中指定不同的大小限制。 然而,您必须提交Grafana Cloud的支持票,以提高后端的限制.

#### Gzipping 选项

CLI提供了两种不同的gzipping选项来优化上传:

1.  **Gzip 内容`-g, --gzip-contents`(中文(简体) )**:在上传前将多源映射文件压缩为tarball. 文件采用流式处理方式,累积到达到30MB极限后再创建并上传出每个柏球. 这在同时上传多个文件时有用.
    
2.  **Gzip 有效载荷`-z, --gzip-payload`(中文(简体) )**:使用gzip内容编码压缩HTTP有效载荷本身. 这可以大大地缩小上传大小,对大源地图文件特别有用.
    

Gzip 有效载荷示例 :

```bash
npx faro-cli upload \
  --endpoint "your-faro-sourcemap-api-url" \
  --app-id "your-app-id" \
  --api-key "your-api-key" \
  --stack-id "your-stack-id" \
  --bundle-id "your-bundle-id" \
  --output-path "./dist" \
  --patterns "*.map" \
  --gzip-payload \
  --verbose
```

可以同时使用两种选项进行最大压缩 :

```bash
npx faro-cli upload \
  --endpoint "your-faro-sourcemap-api-url" \
  --app-id "your-app-id" \
  --api-key "your-api-key" \
  --stack-id "your-stack-id" \
  --bundle-id "your-bundle-id" \
  --output-path "./dist" \
  --patterns "*.map" \
  --gzip-contents \
  --gzip-payload \
  --verbose
```

对于 `metro upload`,击出是 **默认** (单位:千美元) `.map` 被装作被涂抹的焦油球。 过 `--no-gzip` 输入原始 `.map` JSON 取而代之 —— 在调试上传到管理器的代理服务器时有用 `Content-Encoding`。 。 。 .

#### 使用代理服务器

如果您需要通过代理服务器传送请求, 您可以使用 `--proxy` 选项 :

```bash
npx faro-cli upload \
  --endpoint "your-faro-sourcemap-api-url" \
  --app-id "your-app-id" \
  --api-key "your-api-key" \
  --stack-id "your-stack-id" \
  --bundle-id "your-bundle-id" \
  --output-path "./dist" \
  --proxy "your-proxy:port" \
  --proxy-user "user:pass" \
  --verbose
```

代理 URL 将使用 `--proxy` 参数。 如果您的代理需要认证, 您可以使用 `--proxy-user` 选项(或 `-U`以格式提供全权证书 `username:password`。同样的 `--proxy` 财务报告和审定财务报表 `--proxy-user` 旗子同样使用 `metro upload`。 。 。 .

### 将套装ID注入 JavaScript 文件

对于不使用Webpack或Rollup的应用程序,或者在需要将捆绑的ID添加到已经建成的JavaScript文件时,可以使用 `inject-bundle-id` 命令 :

```bash
npx faro-cli inject-bundle-id \
  --bundle-id "your-bundle-id" \
  --app-name "your-app-name" \
  --files "dist/**/*.js" \
  --verbose
```

此命令将 :

1.  定位所有符合指定 glob 模式的 JavaScript 文件
2.  检查每个文件是否有捆绑的ID片段
3.  将捆绑的ID片断保存到没有它的文件
4.  将捆绑的ID导出到环境变量, 以便日后与其他命令一起使用

#### 选项

-   `--bundle-id, -b`: 需要注入的捆绑ID( 空白生成随机ID)
-   `--app-name, -n`: 捆绑ID片断中使用的应用程序名称
-   `--files, -f`: 要匹配的文件模式( 可指定多种模式)
-   `--verbose, -v`: 启用动词记录
-   `--dry-run, -d`: 只打印将修改的文件而不修改

#### 实例

生成随机捆绑的ID并注入所有JS文件:

```bash
npx faro-cli inject-bundle-id \
  --app-name "my-app" \
  --files "dist/**/*.js" \
  --verbose
```

首先进行干线运行, 查看哪些文件将被修改 :

```bash
npx faro-cli inject-bundle-id \
  --bundle-id "your-bundle-id" \
  --app-name "my-app" \
  --files "dist/**/*.js" \
  --dry-run \
  --verbose
```

> **只有网络.** 这个命令是针对尚未整合出法罗插件的Web捆绑者所生产的已经建成的JavaScript捆绑. 反应原生( Metro) 流通过 Metro 时间注入捆绑的ID `@grafana/faro-metro-plugin`序言,所以你别跑 `inject-bundle-id` 在RN捆绑.

### 将 Git Hash 注入 JavaScript 文件

用于无法访问的应用程序 `.git` 目录,或者在建设后的管道中,如果您想要将已经建成的JavaScript文件印入执行散列,请使用 `inject-git-hash` 命令 :

```bash
npx faro-cli inject-git-hash \
  --app-name "your-app-name" \
  --files "dist/**/*.js" \
  --verbose
```

何时 `--git-hash` 未提供命令,命令通过 `git rev-parse HEAD`。如果散列无法解决,则命令以非零错误代码退出.

**CI的明确散列:**

```bash
npx faro-cli inject-git-hash \
  --git-hash "$GITHUB_SHA" \
  --app-name "your-app-name" \
  --files "dist/**/*.js"
```

#### 选项

-   `--git-hash, -g`:基特将散列注射. 自动检测通过 `git rev-parse HEAD` 如果未提供; 如果无法解决,则有出错.
-   `--app-name, -n`: git 散列片段中使用的应用程序名( 需要)
-   `--files, -f`: 要匹配的文件模式( 支持 glob 模式)
-   `--verbose, -v`: 启用动词记录
-   `--dry-run, -d`: 在不修改的情况下打印哪些文件

### 使用 Bundler 插件

使用 Faro 捆绑插件时, 您可以设置 `skipUpload` 选项到 `true` 在插件配置中,在构建过程中跳过上传源图,取而代之的是使用 CLI 后上传.

#### 滚动示例

```js
// rollup.config.js
import faroUploader from '@grafana/faro-rollup-plugin';

export default {
  // ... other rollup config
  plugins: [
    // ... other plugins
    faroUploader({
      // 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: 'https://faro-api-prod-us-east-0.grafana.net/faro/api/v1',
      appName: 'my-app',
      appId: 'your-app-id',
      apiKey: 'your-api-key',
      stackId: 'your-stack-id',
      skipUpload: true, // Skip uploading during build
      verbose: true,
    }),
  ],
};
```

然后,在构建之后,您可以使用 CLI 上传源图 :

```bash
npx faro-cli upload \
  --endpoint "your-faro-sourcemap-api-url" \
  --app-id "your-app-id" \
  --api-key "your-api-key" \
  --stack-id "your-stack-id" \
  --bundle-id env \
  --app-name "my-app" \
  --output-path "./dist" \
  --verbose
```

注意使用 `--bundle-id env` 财务报告和审定财务报表 `--app-name "my-app"` 从捆绑器插件设置的环境变量读取捆绑ID.

#### 网页包示例

```js
// webpack.config.js
const FaroSourceMapUploaderPlugin = require('@grafana/faro-webpack-plugin');

module.exports = {
  // ... other webpack config
  plugins: [
    // ... other plugins
    new FaroSourceMapUploaderPlugin({
      endpoint: 'https://faro-api-prod-us-east-0.grafana.net/faro/api/v1',
      appName: 'my-app',
      appId: 'your-app-id',
      apiKey: 'your-api-key',
      stackId: 'your-stack-id',
      skipUpload: true, // Skip uploading during build
      verbose: true,
    }),
  ],
};
```

#### Metro 示例( 本地反应)

`@grafana/faro-metro-plugin` 是Webpack/Rollup 本地反应插件的等效。 它支持同样的 `skipUpload` 选项,含义相同: `true`,插件不会上传.

```js
// 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://faro-api-prod-us-east-0.grafana.net/faro/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),
);
```

手册引用每个平台的形状相同:

```bash
npx faro-cli metro upload \
  --map "path/to/your.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"
```

每个连接设置(和 `--bundle-id`)也接受匹配 `FARO_*` 如果旗子被省略了, 反倒会掉下来, 所以这个步骤已经输出了全部 `FARO_*` 设置可以调用 `faro-cli metro upload --map …` 没有别的了.

### 生成卷轴命令

如果喜欢直接使用卷曲,可以生成卷曲命令. 网络示例 :

```bash
npx faro-cli curl \
  --endpoint "your-faro-sourcemap-api-url" \
  --app-id "your-app-id" \
  --api-key "your-api-key" \
  --stack-id "your-stack-id" \
  --bundle-id "your-bundle-id" \
  --file "./dist/main.js.map"
```

原生反应( 地铁) —— 相同 `curl` 子命令,仅指点 `--file` 地点 `.map` 您想要上传和通过 捆绑的ID 匹配您的运出 JS:

```bash
npx faro-cli curl \
  --endpoint "$FARO_SOURCEMAP_ENDPOINT" \
  --app-id   "$FARO_SOURCEMAP_APP_ID" \
  --api-key  "$FARO_SOURCEMAP_API_KEY" \
  --stack-id "$FARO_SOURCEMAP_STACK_ID" \
  --bundle-id "$FARO_BUNDLE_ID" \
  --file     "path/to/your.map"
```

您也可以生成使用 gzip 压缩的卷曲命令 :

```bash
npx faro-cli curl \
  --endpoint "your-faro-sourcemap-api-url" \
  --app-id "your-app-id" \
  --api-key "your-api-key" \
  --stack-id "your-stack-id" \
  --bundle-id "your-bundle-id" \
  --file "./dist/main.js.map" \
  --gzip-payload
```

您也可以生成一个使用代理的卷曲命令 :

```bash
npx faro-cli curl \
  --endpoint "your-faro-sourcemap-api-url" \
  --app-id "your-app-id" \
  --api-key "your-api-key" \
  --stack-id "your-stack-id" \
  --bundle-id "your-bundle-id" \
  --file "./dist/main.js.map" \
  --proxy "http://proxy.example.com:8080" \
  --proxy-user "username:password"
```

这将输出一个可以手动复制和运行的卷轴命令 .

## 选项

### 上传命令

-   `-e, --endpoint <url>`: Faro API 端点 URL( 需要) - 在前端可观察性插件中查找此值 **设置** - > (中文) **来源地图** - > (中文) **配置源地图上传**
-   `-a, --app-id <id>`: Faro 应用程序 ID( 需要)
-   `-k, --api-key <key>`:法罗API密钥. 倒计时 `FARO_SOURCEMAP_API_KEY` 当省略时.
-   `-s, --stack-id <id>`: Faro sack ID( 需要) - 在前端可观察性插件中查找此值 **设置** - > (中文) **来源地图** - > (中文) **配置源地图上传**
-   `-b, --bundle-id <id>`: Bundle ID(需要,可以设置为"env"从环境变量读取)
-   `-o, --output-path <path>`: 含有源地图的目录路径( 需要)
-   `-n, --app-name <name>`: 应用程序名称(用于在环境变量中查找 bundId)
-   `-k, --keep-sourcemaps`: 上传后保留源地图( 默认: 假)
-   `-g, --gzip-contents`: 上传前将源图压缩为 tarball; 文件处理方式为流式, 累积到大小限制( 默认: 假)
-   `-z, --gzip-payload`: Gzip HTTP 有效载荷用于更小的上传( 默认: 假)
-   `-v, --verbose`: 启用动词记录( 默认: 假)
-   `-r, --recursive`: 递归搜索源地图的子目录( 默认: 假)
-   `-i, --max-upload-size <size>`: 最大上传大小为字节,默认为30MB. 法罗API对单个文件默认上传有30MB的限制. 在特殊情况下,可以通过联系Grafana Cloud支持来改变这一限制.
-   `-x, --proxy <url>`: 用于 cURL 请求的代理 URL( 可选)
-   `-U, --proxy-user <user:password>`: 代理认证的用户名和密码( 可选)

### 注入- git- hash 命令

-   `-g, --git-hash <hash>`: Git 将散列注射(自动通过 `git rev-parse HEAD` 如果未提供; 如果无法解决则有出错的退出)
-   `-n, --app-name <name>`: git 散列片段中使用的应用程序名( 需要)
-   `-f, --files <patterns...>`: 要匹配的文件模式( 支持 glob 模式)
-   `-v, --verbose`: 启用动词记录( 默认: 假)
-   `-d, --dry-run`: 打印将修改哪些文件而不做修改( 默认: 假)

### 曲线命令

-   `-e, --endpoint <url>`: Faro API 端点 URL( 需要) - 在前端可观察性插件中查找此值 **设置** - > (中文) **来源地图** - > (中文) **配置源地图上传**
-   `-a, --app-id <id>`: Faro 应用程序 ID( 需要)
-   `-k, --api-key <key>`: Faro API 密钥( 需要)
-   `-s, --stack-id <id>`: Faro sack ID( 需要) - 在前端可观察性插件中查找此值 **设置** - > (中文) **来源地图** - > (中文) **配置源地图上传**
-   `-b, --bundle-id <id>`: Bundle ID(需要,可以设置为"env"从环境变量读取)
-   `-f, --file <path>`: 源地图文件路径( 需要)
-   `-n, --app-name <name>`: 应用程序名称(用于在环境变量中查找 bundId)
-   `-t, --content-type <type>`: 上传的内容类型( 默认为“ 应用程序/ json ”)
-   `-z, --gzip-payload`: 生成一个命令, 以 gzips 有效载荷( 默认: 假)
-   `-x, --proxy <url>`: 用于 cURL 请求的代理 URL( 可选)
-   `-U, --proxy-user <user:password>`: 代理认证的用户名和密码( 可选)

### 地铁上传命令( E)`metro upload`(中文(简体) )

-   `--map <path>` (需要): 通往 `.map` 要上传的文件。 CLI确实如此 不从此路径获取或自动检测到此路径——呼叫者选择文件.
-   `-e, --endpoint <url>`: 法罗源图 API Base URL. 倒计时 `FARO_SOURCEMAP_ENDPOINT`。 。 。 .
-   `-a, --app-id <id>`: 法罗应用id. 倒计时 `FARO_SOURCEMAP_APP_ID`。 。 。 .
-   `-s, --stack-id <id>`: 格拉法纳 云叠取出. 倒计时 `FARO_SOURCEMAP_STACK_ID`。 。 。 .
-   `-k, --api-key <key>`: Bearer API 键. 倒计时 `FARO_SOURCEMAP_API_KEY`。 。 。 .
-   `-b, --bundle-id <id>`与运出JS捆绑物匹配的包装ID. 倒计时 `FARO_BUNDLE_ID`。 。 。 .
-   `--no-gzip`: 将原始的 `.map` JSON代替了被咬了的焦油球.
-   `-v, --verbose`:活塞伐木.
-   `--dry-run`: 显示要上传和退出的内容 .
-   `-i, --max-upload-size <size>`: 最大上传大小为字节( 默认: 30MB) .
-   `-x, --proxy <url>`, (中文(简体) ), `-U, --proxy-user <user:password>`:与其他子命令相同.

#### 连接设置优先

对于每个连接设置和捆绑的ID,解析是"第一个非空取胜": **CLI 旗帜 > 匹配 Env var**。 。 。 .

| 设置 | CLI 旗帜 | 信封倒置 |
| --- | --- | --- |
| 终点基地 | `--endpoint` | `FARO_SOURCEMAP_ENDPOINT` |
| 应用代码 | `--app-id` | `FARO_SOURCEMAP_APP_ID` |
| 堆叠编号 | `--stack-id` | `FARO_SOURCEMAP_STACK_ID` |
| API 密钥 | `--api-key` | `FARO_SOURCEMAP_API_KEY` |
| 套装标识 | `--bundle-id` | `FARO_BUNDLE_ID` |

地图路径( E)`--map`)为 **所需经费** 并且没有内伏 或自动检测.

#### 验证和退出代码

这个 `.map` 在任何上传尝试之前,解析并进行结构验证。 CLI从不检查或改写 `mappings`, (中文(简体) ), `sources`,或 `sourcesContent`; 如果 `file` 属性缺失, 它从地图文件名中设置, 因此下游符号可以按键 .

| 退出代码 | 含义 |
| --- | --- |
| `0` | 上传成功(或) `--dry-run` 结束). |
| `1` | 尝试上传, API 拒绝了( 重运行 ) `--verbose`) (中文(简体) ). |
| `2` | 飞行前失败: 缺少所需的设置, 缺少/ 无法解析的地图, 非 v3 地图, 或地图超过大小限制 . |
| `3` | 地图被解析为 v3 但它的 `sources` 阵列为空 。 无论产生什么结果,文件都发布了一个结构有效但无用的地图;调查CLI的上游. 将 CI 线连接到此代码 . |

## 许可证

阿帕奇 - 2.0

## 常见问题

### @grafana/faro-cli 是什么？

用于上传源图到 Faro 源图 API 的 CLI

### 如何安装 @grafana/faro-cli？

在项目目录运行 npm install @grafana/faro-cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 faro-cli，可以用 npx faro-cli 直接运行。

### @grafana/faro-cli 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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

