Application Real-Time Monitoring Service：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 才能展示源碼上下文。

Chunk URL 含括弧時無法自動解析 SourceMap

當 webpack 打包產物的 chunk URL 路徑中包含括弧等特殊字元（例如 Next.js App Router 路由分組格式 /app/(groupName)/page/）時，ARMS 的 binary_images 欄位無法正確解析 UUID，導致 SourceMap 自動匹配失敗。同一異常中不含括弧的 chunk URL 解析正常。這是 ARMS 的已知解析限制，暫無法自助解決。建議在 webpack 配置中避免在 chunk URL 路徑中使用括弧，以確保 SourceMap 自動匹配正常工作。