RUM Source Maps 与 Symbols

MoleSignal 使用调试产物还原压缩后的 JavaScript、混淆后的 Dart 或 Android，以及 Android、 iOS 原生堆栈帧。所有调试产物统一通过 /api/v1/debug-artifacts 管理。

选择产物类型

运行时	`kind`	`platform`	文件
Browser JavaScript	`javascript_sourcemap`	`web`	外部 `.map` 文件
Flutter Web	`javascript_sourcemap`	`flutter`	`main.dart.js.map` 或其他生成的 `.map`
Flutter Android 或 iOS AOT	`flutter_symbols`	`android` 或 `ios`	Flutter `--split-debug-info` 生成的 `.symbols`
Android R8	`android_mapping`	`android`	Release `mapping.txt`
Android NDK	`android_native_symbols`	`android`	未剥离的 ELF 动态库
Apple 原生	`apple_dsym`	`ios`	匹配 `.dSYM` 包内的 DWARF 二进制文件

支持原始文件与 gzip 压缩文件。上传文件最大 50 MiB；gzip 解压后最大 256 MiB。

匹配构建标识

MoleSignal 根据 RUM Error 的构建标识选择调试产物：

上传字段	对应 RUM 值	规则
`application_id`	`application` 或 `application_id`	必须完全一致
`service`	SDK `service`	必须完全一致并区分大小写
`release`	SDK `version` 或事件 `release`	必须完全一致并区分大小写
`kind`	堆栈帧类型	从支持的产物表中选择
`platform`	事件平台	按上表使用 `web`、`flutter`、`android` 或 `ios`
`architecture`	事件架构	移动端与原生产物应填写，例如 `arm64` 或 `x86_64`
`debug_id`	事件或帧的 Debug ID	使用相同的 Flutter Build ID、ELF Build ID 或 Mach-O UUID
文件名	运行时模块或 Bundle	Browser Map 必须使用 `<已部署 Bundle 文件名>.map`

常见 ABI 别名会自动规范化。例如，arm64-v8a 与 aarch64 会转换为 arm64，amd64 与 x64 会转换为 x86_64。十六进制 Debug ID 与 UUID 比较时会忽略大小写、花括号、连字符和开头的 0x。

application_id、service、release、architecture 与 debug_id 必须和产物来自同一条构建流水线。标识过期或存在歧义时，错误事件仍会保留，但符号化状态会是 missing 或 partial。

Browser 示例

每次构建时，为 service 和 version 设置稳定值：

import { initRum } from '@molesignal/browser-rum';

initRum({
  applicationId: 'checkout-web',
  clientToken: 'msrum_your_client_token',
  site: 'https://molesignal.example.com',
  service: 'web-frontend',
  version: '2026.08.04.1',
});

上传 Source Map 时使用相同标识和实际部署的 Bundle 文件名：

上传字段	SDK 字段	示例
应用 ID	`applicationId`	`checkout-web`
服务	`service`	`web-frontend`
版本	`version`	`2026.08.04.1`
文件	生成的 `.map` 文件	`app.8f312.js.map`

已部署帧 URL 以 /assets/app.8f312.js 结尾时，需要上传 app.8f312.js.map。所有按需加载 Chunk 的 Source Map 都要上传，不能只上传主 Bundle。

在页面中上传

在构建中启用 Source Map

在生产构建中生成外部 Source Map。如果安全策略要求源码保持私有，请不要把 Source Map 部署到公网。

打开上传页面

进入 RUM → RUM 设置 → Source Maps 与 Symbols，然后点击 上传调试产物。

填写构建标识

选择产物类型与平台，填写完全一致的应用、服务和版本。移动端产物还要填写架构与 Debug ID，然后选择生成的文件。

验证符号化

从该版本发送一个错误，打开 RUM → 错误，确认堆栈已显示原始源码位置。

准备 Release 产物

Web
Flutter Android
Flutter iOS
Android 原生
iOS 原生

使用实际部署的 Browser Bundle 生成外部 Source Map。源码不允许公开时，仅把 .map 文件保存在私有发布流水线中。构建 Flutter Web 时启用 Source Map：

flutter build web \
  --release \
  --source-maps \
  --dart-define=MOLESIGNAL_VERSION="${RELEASE_VERSION}" \
  --dart-define=MOLESIGNAL_ARCHITECTURE=javascript \
  --dart-define=MOLESIGNAL_DEBUG_ID="${BUILD_ID}"

上传 main.dart.js.map 时使用 kind=javascript_sourcemap、platform=flutter 与 architecture=javascript。

为每个生产 ABI 生成独立的 Flutter Symbols：

flutter build apk \
  --release \
  --obfuscate \
  --split-debug-info=build/molesignal-symbols/android-arm64 \
  --target-platform=android-arm64 \
  --dart-define=MOLESIGNAL_VERSION="${RELEASE_VERSION}" \
  --dart-define=MOLESIGNAL_ARCHITECTURE=arm64 \
  --dart-define=MOLESIGNAL_DEBUG_ID="${BUILD_ID}"

上传 app.android-arm64.symbols 时使用 kind=flutter_symbols、platform=android、 architecture=arm64 与 debug_id=${BUILD_ID}。

从 Release IPA 构建生成 Flutter AOT Symbols：

flutter build ipa \
  --release \
  --obfuscate \
  --split-debug-info=build/molesignal-symbols/ios-arm64 \
  --dart-define=MOLESIGNAL_VERSION="${RELEASE_VERSION}" \
  --dart-define=MOLESIGNAL_ARCHITECTURE=arm64 \
  --dart-define=MOLESIGNAL_DEBUG_ID="${BUILD_ID}"

上传 app.ios-arm64.symbols 时使用 kind=flutter_symbols、platform=ios、 architecture=arm64 与 debug_id=${BUILD_ID}。

保留每个 R8 Release 的 app/build/outputs/mapping/release/mapping.txt，并使用 kind=android_mapping、platform=android 上传。为每个 NDK ABI 保留未剥离的 ELF .so。使用平台工具链提取 Build ID，再使用 kind=android_native_symbols、platform=android、规范化架构，以及 Crash Frame 上报的相同 Build ID 上传。

读取归档 dSYM 的 UUID，并按需压缩 DWARF 二进制文件：

dwarfdump --uuid Checkout.app.dSYM
gzip -k Checkout.app.dSYM/Contents/Resources/DWARF/Checkout

上传 DWARF 文件或 .gz 时使用 kind=apple_dsym、platform=ios、匹配架构，并将规范化的 Mach-O UUID 写入 debug_id。

从 CI 上传

使用具有 streams.configure 权限的管理 Token。不得把该 Token 写入 Browser 或移动应用，也不得使用公开的 msrum_ Client Token 管理调试产物。

curl --fail-with-body \
  -H "Authorization: Bearer ${MOLESIGNAL_TOKEN}" \
  -F "application_id=${APPLICATION_ID}" \
  -F "service=${SERVICE}" \
  -F "release=${RELEASE_VERSION}" \
  -F "kind=${ARTIFACT_KIND}" \
  -F "platform=${PLATFORM}" \
  -F "architecture=${ARCHITECTURE}" \
  -F "debug_id=${DEBUG_ID}" \
  -F "file=@${ARTIFACT_PATH}" \
  "${MOLESIGNAL_SITE}/api/v1/debug-artifacts"

只有需要创建通用回退产物时，才将 architecture 或 debug_id 留空。移动端使用精确构建标识可以避免匹配歧义。通过 GET /api/v1/debug-artifacts 列出产物，可按 application_id、service、kind 或 platform 筛选。通过 DELETE /api/v1/debug-artifacts/{id} 删除单个产物。列出产物需要 streams.read，上传与删除需要 streams.configure。

发布检查清单

保留实际部署二进制或 Bundle 生成的产物。
在任何错误可能被记录之前设置不可变的 SDK 版本。
保持应用、服务、版本、架构与 Debug ID 和当前构建一致。
上传全部 Web Chunk Source Map 与所有已发布移动端架构的产物。
只在发布流水线中保存管理 Token。
部署后发送一个受控错误，并确认堆栈帧已生成还原后的 original_* 字段。

Browser RUM SDK

配置 Browser 应用、服务与版本标识。

Flutter App RUM SDK

配置 Flutter 构建标识与错误采集。

快速上手

观察

可靠性

AI 运维

数据

协作

管理

部署与运维

RUM Source Maps 与 Symbols

选择产物类型

匹配构建标识

Browser 示例

在页面中上传

准备 Release 产物

从 CI 上传

发布检查清单

Browser RUM SDK

Flutter App RUM SDK

​选择产物类型

​匹配构建标识

​Browser 示例

​在页面中上传

​准备 Release 产物

​从 CI 上传

​发布检查清单

Browser RUM SDK

Flutter App RUM SDK

选择产物类型

匹配构建标识

Browser 示例

在页面中上传

准备 Release 产物

从 CI 上传

发布检查清单