Web & H5 端插件自动上传 SourceMap

Webpack

1. 安装 RUM Webpack 前端构建工具插件 npm 包。

   npm install -D @arms/rum-webpack-plugin

2. 集成并配置 Webpack 插件。

   生产构建建议使用 hidden-source-map，避免在 JavaScript 产物中暴露 SourceMap URL。

   const { rumWebpackPlugin } = require('@arms/rum-webpack-plugin');
   
   module.exports = {
     mode: 'production',
     devtool: 'hidden-source-map',
     plugins: [
       rumWebpackPlugin({
         workspace: 'your-workspace',
         serviceId: 'your-rum-service-id',
         version: 'your-release-version',
         region: 'cn-hangzhou',
         accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
         accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
         stsToken: process.env.ALIBABA_CLOUD_SECURITY_TOKEN,
         clearSourceMap: true,
       }),
     ],
   };

   说明

   Webpack 在 mode === 'development' 或 NODE_ENV === 'development' 时会跳过 SourceMap 处理和上传。请使用非 development 构建执行生产 SourceMap 上传。

Vite

1. 安装 RUM Vite 前端构建插件 npm 包。

   npm install -D @arms/rum-vite-plugin

2. 集成并配置 Vite 插件。

   import { defineConfig } from 'vite';
   import { rumVitePlugin } from '@arms/rum-vite-plugin';
   
   export default defineConfig({
     build: {
       sourcemap: true,
     },
     plugins: [
       rumVitePlugin({
         workspace: 'your-workspace',
         serviceId: 'your-rum-service-id',
         version: 'your-release-version',
         region: 'cn-hangzhou',
         accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
         accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
         stsToken: process.env.ALIBABA_CLOUD_SECURITY_TOKEN,
         clearSourceMap: true,
       }),
     ],
   });

   说明

   build.sourcemap 可以设置为 true 或 'hidden'。不要设置为 'inline'。

检查 SourceMap 文件

当 clearSourceMap: false 时，可以在构建目录打开 .map 文件。顶层存在格式正确的 debugId 表示 SourceMap 注入成功，例如：

{
  "version": 3,
  "file": "index.js",
  "sources": ["webpack://app/src/index.ts"],
  "sourcesContent": ["throw new Error('test');"],
  "mappings": "AAAA",
  "debugId": "e4f083d6-b8d8-4cae-a0ea-16f2e83a6be1"
}

sourcesContent 应存在且内容非空，否则 RUM 可能只能还原文件位置，无法展示源码上下文。

检查浏览器运行时

打开已经部署的页面，在浏览器控制台执行：

window._armsRumDebugIds;

返回对象中包含 UUID 映射，表示当前页面的 JavaScript 文件已经注册 debugId。插件还会尝试在 globalThis、self、global、document.defaultView 以及可访问的 parent/top window 中同步注册，以适配 iframe 和微前端场景。

检查上传结果

在 RUM 应用的文件管理页面确认：

• SourceMap 文件已出现。

• 文件版本与插件中的 version 一致。

• UUID 与构建产物中的 debugId 一致。

构建日志提示找不到 SourceMap

检查构建工具是否生成了独立的 .map 文件。不要使用 inline/eval SourceMap，并确认 JavaScript 文件与 .map 文件的名称和路径关系没有被后处理脚本破坏。

上传成功，但异常详情没有源码

依次检查：

1. .map 文件中是否存在非空 sourcesContent。

2. SourceMap 的 debugId 是否与异常堆栈上报的 UUID 一致。

3. workspace、serviceId、version 和 region 是否与目标 RUM 应用一致。

4. 上传后的文件是否出现在目标应用的文件管理页面。

Webpack 没有上传文件

确认 mode 和 NODE_ENV 均不是 development，并检查是否生成了外部 SourceMap。

是否支持自定义 OSS Bucket

不支持。上传地址和表单参数由 OpenAPI 返回，插件不暴露 Bucket 配置。

如何避免 SourceMap 被部署到公网

Webpack 可使用 hidden-source-map。同时设置 clearSourceMap: true，插件会在每个 SourceMap 上传成功后删除对应的本地 .map 文件。

提示当前 Node.js 不支持

将构建环境升级到 Node.js 20 LTS，或 Node.js 22 及以上版本。Vite 插件使用的依赖不支持 Node.js 18 和 21。

SourceMap 超过大小限制

单个 SourceMap 文件不能超过 50 MiB。可以通过代码拆分、减少内联源码体积或调整构建策略缩小文件，但必须保留足够的 sourcesContent 才能展示源码上下文。