Application Real-Time Monitoring Service:Upload automático de source maps com o plugin para web e H5

Webpack

1. Instale o pacote npm do plugin de ferramenta de build do RUM para Webpack.

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

2. Integre e configure o plugin do Webpack.

   Em builds de produção, use hidden-source-map para evitar expor a URL do source map na saída 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,
       }),
     ],
   };

   O Webpack ignora o processamento e o upload do source map quando mode === 'development' ou NODE_ENV === 'development'. Use um build diferente de desenvolvimento para enviar os source maps de produção.

Vite

1. Instale o pacote npm do plugin de ferramenta de build do RUM para Vite.

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

2. Integre e configure o plugin do 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,
       }),
     ],
   });

   Defina o parâmetro build.sourcemap como true ou 'hidden'. Não use 'inline'.

Verifique os arquivos de source map

Se clearSourceMap: false, abra um arquivo .map no diretório de saída do build. Um debugId formatado corretamente no nível superior indica injeção bem-sucedida. Exemplo:

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

O campo sourcesContent deve estar presente e preenchido. Se estiver ausente ou vazio, o RUM poderá restaurar apenas a localização do arquivo, sem exibir o contexto do código-fonte.

Verifique o runtime do navegador

Abra a página implantada e execute o seguinte comando no console do navegador:

window._armsRumDebugIds;

Se o objeto retornado contiver mapeamentos de UUID, os arquivos JavaScript da página atual registraram um debugId. O plugin também registra o debugId em globalThis, self, global, document.defaultView e janelas pai/top acessíveis para oferecer suporte a cenários de iframe e micro-frontends.

Verifique os resultados do upload

Na página File Management do aplicativo RUM, confirme se:

• Os arquivos de source map aparecem na lista.

• A versão do arquivo corresponde à version configurada no plugin.

• O UUID corresponde ao debugId na saída do build.

Os logs de build relatam que os arquivos de source map não foram encontrados

Verifique se a ferramenta de build gera arquivos .map separados. Evite source maps inline ou eval. Confirme também se scripts de pós-processamento não modificaram os nomes e caminhos dos arquivos JavaScript e .map.

O upload foi bem-sucedido, mas a página de detalhes da exceção não exibe o código-fonte

Verifique os itens a seguir nesta ordem:

1. O arquivo .map contém um sourcesContent não vazio?

2. O debugId no source map corresponde ao UUID reportado no stack trace da exceção?

3. Os valores de workspace, serviceId, version e region correspondem ao aplicativo RUM de destino?

4. O arquivo enviado aparece na página File Management do aplicativo de destino?

O Webpack não envia arquivos

Confirme se nem mode nem NODE_ENV estão definidos como development. Verifique também se o build gera arquivos externos de source map.

Posso usar um bucket OSS personalizado?

Não. A OpenAPI retorna o endpoint de upload e os parâmetros de formulário. O plugin não expõe configurações de bucket.

Como impedir a implantação dos source maps na internet pública?

No Webpack, use hidden-source-map. Defina também clearSourceMap: true. O plugin exclui o arquivo local .map correspondente após cada upload bem-sucedido.

Erro indica que a versão atual do Node.js não suporta determinados recursos

Atualize o ambiente de build para Node.js 20 LTS ou Node.js 22 e superior. As dependências do plugin Vite não suportam Node.js 18 ou 21.

Um arquivo de source map excede o limite de tamanho

Um único arquivo de source map não pode exceder 50 MiB. Reduza o tamanho do arquivo com code splitting, diminuição do conteúdo de source inline ou ajuste da configuração de build. Mantenha sourcesContent suficiente para exibir o contexto do código-fonte.