通过 CMS2 CLI 上传 RUM 符号表文件-云监控(CMS)-阿里云帮助中心

应用上线后，压缩、混淆或编译产生的错误堆栈难以直接定位源码问题。CMS2 CLI 提供 aliyun cms2 rum upload 命令，支持上传 SourceMap、ProGuard mapping、dSYM、Native Symbol、name-cache、PDB 等符号表文件。上传完成后，RUM 能够将线上错误堆栈还原为可读的源码文件名、方法名、函数名和行号。

前提条件

使用 CLI 上传前，确保已完成以下操作：

已创建用户体验监控应用并获取应用 Workspace 和 ServiceId，具体操作参见接入Web & H5应用、接入小程序应用和Android应用监控。
安装阿里云 CLI，请参见安装/更新 CLI，可以通过 aliyun cms2 --help 验证 CMS2 CLI 是否可用。

已配置包含 CMS 权限的 CLI 访问凭证，配置命令 aliyun configure，权限策略示例：

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "cms:*",
      "Resource": "*"
    }
  ]
}

命令语法与参数

上传命令的基本语法如下：

aliyun cms2 rum upload \
  --workspace <workspace-name> \
  --service-id <rum-service-id> \
  --version <release-version> \
  --file-kind <file-kind> \
  --dir <artifact-dir>

该命令会扫描本地符号表文件，向 CMS 请求短期有效的 RUM 上传策略，并将文件上传至指定存储位置。

参数	是否必填	说明
`--workspace`	是	CMS 工作空间名称。
`--service-id`	是	RUM 服务 ID。
`--version`	是	发布版本或构建版本。需与 SDK 上报的版本保持一致。
`--file-kind`	是	符号表文件类型。
`--dir`	否	扫描目录。`--dir` 和 `--file` 至少设置一个。
`--file`	否	指定单个文件。可重复设置。
`--dry-run`	否	仅扫描和校验文件，不请求上传策略、不上传，也不会修改本地文件。
`--inject-debug-id`	否	SourceMap 缺少 Debug ID 时，向 companion JS 注入 RUM debug ID runtime snippet；不会改写 SourceMap 文件。
`--debug-id`	否	显式指定 Debug ID 或 Build ID。除 `dsym` 外，会优先使用该值；`dsym` 上传策略不传 Debug ID。
`--max-files`	否	单次命令最多上传的文件数，默认值为 `1000`。
`--recursive`	否	是否递归扫描 `--dir` 指定的目录，默认值为 `true`。
`-o json`	否	以 JSON 格式输出执行结果。

文件类型

--file-kind 支持以下取值：

取值	说明
`sourcemap`	SourceMap 文件，适用于 Web、H5、小程序、React Native JS 堆栈还原。
`proguard`	Android ProGuard/R8 mapping 文件。
`dsym`	iOS dSYM 文件或目录。
`native-symbol`	原生符号文件，例如 Android Native Symbol。
`pdb`	Windows PDB 文件。

各端上传命令

以下示例默认在应用项目根目录执行。--file 和 --dir 支持相对路径或绝对路径；相对路径以当前执行命令的目录为准。使用 CI/CD 时，建议先切换到项目根目录，或直接使用构建产物的绝对路径，避免工作目录变化导致文件匹配失败。

上传 SourceMap

Web、H5 或小程序 SourceMap 上传示例：

aliyun cms2 rum upload \
  --workspace default-cms-xxx-cn-hangzhou \
  --service-id "$ARMS_RUM_SERVICE_ID" \
  --version "$RELEASE_VERSION" \
  --file-kind sourcemap \
  --dir dist \
  --inject-debug-id

如果 SourceMap 文件缺少 Debug ID，CLI 会提示：

has no debugId; pass --inject-debug-id or --debug-id

此时建议使用 --inject-debug-id，由 CLI 为 companion JS 注入 RUM debug ID runtime snippet。CLI 不会向 SourceMap 文件写入 Debug ID；上传前确认注入后的 JS 文件与 SourceMap 文件会随同一次发布流程一起使用。

上传 Android mapping 文件

Android 应用开启 ProGuard 或 R8 混淆后，可上传 mapping.txt 文件。以下示例默认在 Android/Gradle 项目根目录执行：

aliyun cms2 rum upload \
  --workspace default-cms-xxx-cn-hangzhou \
  --service-id "$ARMS_RUM_SERVICE_ID" \
  --version "$RELEASE_VERSION" \
  --file-kind proguard \
  --file app/build/outputs/mapping/release/mapping.txt

确保上传的 mapping.txt 与线上 APK 或 AAB 来自同一次构建，并对应正确的 build variant。

上传 iOS dSYM 文件

可以上传 .dSYM 目录：

aliyun cms2 rum upload \
  --workspace default-cms-xxx-cn-hangzhou \
  --service-id "$ARMS_RUM_SERVICE_ID" \
  --version "$RELEASE_VERSION" \
  --file-kind dsym \
  --file path/to/Demo.app.dSYM

也可以上传已压缩的 dSYM 文件：

aliyun cms2 rum upload \
  --workspace default-cms-xxx-cn-hangzhou \
  --service-id "$ARMS_RUM_SERVICE_ID" \
  --version "$RELEASE_VERSION" \
  --file-kind dsym \
  --file path/to/Demo.app.dSYM.zip

确保 dSYM 文件与线上 iOS 应用版本匹配。传入 .dSYM 目录时，CLI 会临时压缩为 .dSYM.zip 后上传；dsym 上传策略请求不传 Debug ID，因此 --debug-id 不会作用于 dsym 上传。

上传 Native Symbol

应用包含 Native 代码时，可上传原生符号文件：

aliyun cms2 rum upload \
  --workspace default-cms-xxx-cn-hangzhou \
  --service-id "$ARMS_RUM_SERVICE_ID" \
  --version "$RELEASE_VERSION" \
  --file-kind native-symbol \
  --file path/to/libdemo.so

上传包含符号信息的有效 ELF 文件。CLI 会自动提取 ELF Build ID；如果文件已损坏、不是有效 ELF 文件或缺少 Build ID，CLI 会返回格式校验错误。缺少 Build ID 时，可通过 --debug-id 显式指定。

上传 PDB 文件

Windows 或 PC 应用可上传 PDB 文件：

aliyun cms2 rum upload \
  --workspace default-cms-xxx-cn-hangzhou \
  --service-id "$ARMS_RUM_SERVICE_ID" \
  --version "$RELEASE_VERSION" \
  --file-kind pdb \
  --file path/to/app.pdb

确保 PDB 文件与线上二进制文件来自同一次构建。CLI 会从 PDB CodeView 信息中提取 Debug ID；如果同目录或扫描目录下存在对应的 PE 文件（例如 .exe、.dll、.node、.pyd、.sys），还会使用 PE 的 age 信息修正 Debug ID。无法自动提取时，可通过 --debug-id 显式指定。

预检查上传配置

首次接入或集成 CI/CD 前，建议先使用 --dry-run 检查参数和文件：

aliyun cms2 rum upload \
  --dry-run \
  --workspace default-cms-xxx-cn-hangzhou \
  --service-id "$ARMS_RUM_SERVICE_ID" \
  --version "$RELEASE_VERSION" \
  --file-kind sourcemap \
  --dir dist \
  --inject-debug-id

--dry-run 不会请求上传策略，也不会上传文件；即使同时指定 --inject-debug-id，也不会写回 JS 文件。可用于检查：

必填参数是否完整。
目录下是否存在匹配文件。
文件类型是否正确。
SourceMap 是否具备 Debug ID，或能否定位 companion JS 用于生成运行时关联标识。
Native Symbol 或 PDB 文件格式是否有效。

CI/CD 集成

建议生产构建完成后、发布前上传符号表文件。流水线脚本可通过环境变量传入配置参数：

export ARMS_RUM_SERVICE_ID="<rum-service-id>"
export RELEASE_VERSION="1.0.0"

aliyun cms2 rum upload \
  --workspace default-cms-xxx-cn-hangzhou \
  --service-id "$ARMS_RUM_SERVICE_ID" \
  --version "$RELEASE_VERSION" \
  --file-kind sourcemap \
  --dir dist \
  --inject-debug-id

建议将 workspace、service-id、version 等配置纳入发布流水线变量管理。

常见错误

错误提示	原因	处理方法
`required flag(s) "file-kind" not set`	未指定文件类型。	添加 `--file-kind`。
`one of --dir or --file is required`	未指定上传文件或目录。	添加 `--dir` 或 `--file`。
`no upload files matched the given --file-kind`	未扫描到匹配当前类型的文件。	检查目录、文件后缀和 `--file-kind` 是否正确。
`has no debugId; pass --inject-debug-id or --debug-id`	SourceMap 缺少 Debug ID。	添加 `--inject-debug-id` 或 `--debug-id`。
`--file-kind="xxx" is not a valid value`	文件类型取值错误。	使用支持的 `file-kind` 取值。
`bad magic number`	Native Symbol 文件格式无效。	上传有效的原生符号文件。
`read PDB header ... unexpected EOF`	PDB 文件无效或损坏。	上传完整有效的 PDB 文件。

后续操作

上传完成后，通过 RUM 错误详情或崩溃详情查看堆栈解析效果。如果堆栈未解析，优先检查上传版本、文件类型、Debug ID、UUID、Build ID 以及符号表文件是否与线上版本匹配。\