@grafana/faro-cli

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

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

中文使用文档
文档目录14 节
  1. 安装
  2. 所需资源
  3. 使用量
  4. 上传源代码地图
  5. 将套装ID注入 JavaScript 文件
  6. 将 Git Hash 注入 JavaScript 文件
  7. 使用 Bundler 插件
  8. 生成卷轴命令
  9. 选项
  10. 上传命令
  11. 注入- git- hash 命令
  12. 曲线命令
  13. 地铁上传命令( E) metro upload (中文(简体) )
  14. 许可证

法罗CLI

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

安装

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

或者说

yarn add --dev @grafana/faro-cli

所需资源

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

使用量

上传源代码地图

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

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

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) :

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 读取 用来传递哪个平台的地图.

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

文件大小限制

法罗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 有效载荷示例 :

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

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

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 选项 :

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 命令 :

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文件:

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

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

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 命令 :

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

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

CI的明确散列:

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 后上传.

滚动示例

// 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 上传源图 :

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.

网页包示例

// 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,插件不会上传.

// 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),
);

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

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 … 没有别的了.

生成卷轴命令

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

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:

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 压缩的卷曲命令 :

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

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

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 旗帜信封倒置
终点基地--endpointFARO_SOURCEMAP_ENDPOINT
应用代码--app-idFARO_SOURCEMAP_APP_ID
堆叠编号--stack-idFARO_SOURCEMAP_STACK_ID
API 密钥--api-keyFARO_SOURCEMAP_API_KEY
套装标识--bundle-idFARO_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 共发布 29 个版本,首次发布于 2025/03/14;过去 12 个月发布了 19 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.13.4latest2026/11/0610 天前
0.13.32026/10/2721 天前
0.13.22026/10/151 个月前
0.13.12026/10/061 个月前
0.13.02026/09/221 个月前
0.12.02026/08/292 个月前

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

@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 和提交记录判断。