Application Real-Time Monitoring Service:Unggah source map secara otomatis dengan plugin web dan H5

Webpack

1. Instal paket npm plugin build tool RUM untuk Webpack.

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

2. Integrasikan dan konfigurasikan plugin Webpack.

   Untuk build produksi, gunakan hidden-source-map agar URL source map tidak terekspos di output JavaScript.

   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 melewatkan pemrosesan dan pengunggahan source map ketika mode === 'development' atau NODE_ENV === 'development'. Gunakan build non-development untuk mengunggah source map produksi.

Vite

1. Instal paket npm plugin build tool RUM untuk Vite.

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

2. Integrasikan dan konfigurasikan plugin 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 dapat diatur ke true atau 'hidden'. Jangan atur ke 'inline'.

Periksa file source map

Jika clearSourceMap: false, buka file .map di direktori output build. Kehadiran debugId yang diformat dengan benar di tingkat atas menandakan bahwa penyisipan berhasil. Contoh:

{
  "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 harus ada dan tidak kosong. Jika tidak ada atau kosong, RUM mungkin hanya dapat memulihkan lokasi file dan tidak bisa menampilkan konteks kode sumber.

Periksa waktu proses browser

Buka halaman yang telah dideploy dan jalankan perintah berikut di konsol browser:

window._armsRumDebugIds;

Jika objek yang dikembalikan berisi pemetaan UUID, berarti file JavaScript pada halaman saat ini telah mendaftarkan debugId. Plugin juga mendaftarkan debugId di globalThis, self, global, document.defaultView, serta window induk/atas yang dapat diakses, untuk mendukung skenario iframe dan micro-frontend.

Periksa hasil unggah

Di halaman File Management aplikasi RUM Anda, pastikan bahwa:

• File source map telah muncul.

• Versi file sesuai dengan version yang dikonfigurasi di plugin.

• UUID sesuai dengan debugId di output build.

Log build melaporkan bahwa file source map tidak ditemukan

Periksa apakah build tool Anda menghasilkan file .map terpisah. Jangan gunakan source map inline atau eval, dan pastikan nama file serta path file JavaScript dan file .map tidak diubah oleh skrip post-processing.

Unggah berhasil tetapi halaman detail exception tidak menampilkan kode sumber

Periksa secara berurutan:

1. Apakah file .map berisi sourcesContent yang tidak kosong?

2. Apakah debugId dalam source map sesuai dengan UUID yang dilaporkan dalam jejak stack exception?

3. Apakah workspace, serviceId, version, dan region sesuai dengan aplikasi RUM target Anda?

4. Apakah file yang diunggah muncul di halaman File Management aplikasi target?

Webpack tidak mengunggah file

Pastikan bahwa baik mode maupun NODE_ENV tidak diatur ke development, dan verifikasi bahwa file source map eksternal sedang dihasilkan.

Bisakah saya menggunakan bucket OSS kustom?

Tidak. Titik akhir unggah dan parameter form dikembalikan oleh OpenAPI. Plugin tidak mengekspos konfigurasi bucket.

Bagaimana cara mencegah source map dipublikasikan ke internet publik?

Untuk Webpack, gunakan hidden-source-map. Atur juga clearSourceMap: true. Plugin akan menghapus file lokal .map yang sesuai setelah setiap unggah berhasil.

Saya melihat error bahwa versi Node.js saat ini tidak mendukung fitur tertentu

Upgrade lingkungan build Anda ke Node.js 20 LTS atau Node.js 22 ke atas. Dependensi yang digunakan oleh plugin Vite tidak mendukung Node.js 18 atau 21.

Ukuran file source map melebihi batas

Satu file source map tidak boleh melebihi 50 MiB. Anda dapat mengurangi ukuran file melalui code splitting, mengurangi konten source inline, atau menyesuaikan konfigurasi build Anda. Pastikan Anda tetap menyimpan cukup sourcesContent untuk menampilkan konteks kode sumber.

Pencocokan otomatis source map gagal ketika URL chunk berisi tanda kurung

Ketika URL chunk webpack berisi karakter khusus seperti tanda kurung — misalnya format route group yang digunakan oleh Next.js App Router (/app/(groupName)/page/) — ARMS tidak dapat mengurai UUID dengan benar dari bidang binary_images dalam error JS yang dilaporkan. Akibatnya, pencocokan otomatis source map gagal. URL chunk tanpa tanda kurung dalam exception yang sama diurai secara normal.

Ini merupakan keterbatasan penguraian ARMS yang sudah diketahui. Untuk menghindari masalah ini, konfigurasikan webpack agar tidak menyertakan tanda kurung dalam penamaan path chunk. Misalnya, ubah nama direktori route group Next.js agar tidak menggunakan format (groupName).