Sourcemap是一个信息文件，里面储存着位置信息。也就是说，转换后的代码的每一个位置，所对应的转换前的位置。通过Sourcemap文件，出错的时候，除错工具将直接显示原始代码，而不是转换后的代码。本文介绍如何上传Sourcemap文件，以及利用Sourcemap进行代码反解。

管理Sourcemap

• 管理Sourcemap页面
  
• 版本详情页面
  
  版本详情页面可以在JS错误详情页面单击管理sourcemap跳转过来。

上传Sourcemap

• （推荐，webpack插件）使用@apm-insight-web/upload-sourcemaps-webpack-plugin自动上传
• （推荐，vite插件）使用@apm-insight-web/upload-sourcemaps构造vite插件自动上传
• 使用@apm-insight-web/upload-sourcemaps自动上传
• 使用平台手动上传

（推荐，webpack插件）使用upload-sourcemaps-webpack-plugin

1. 在管理sourcemap页面的顶部，获取鉴权所需的API_KEY和API_TOKEN。
   

2. 执行以下命令，安装插件。

   npm install @apm-insight-web/upload-sourcemaps-webpack-plugin --save-dev
   

3. 在webpack.config.js中添加如下脚本，使用插件。

   const UploadSourcemapsPlugin = require('@apm-insight-web/upload-sourcemaps-webpack-plugin').default;
   
   const config = {
     plugins: [
       new UploadSourcemapsPlugin({
         app_id: 123456,
         paths: ['./dir1', './dir2'],  // 包含 sourcemap 文件的路径，我们会从中上传符号表文件到平台, 目前只支持单层目录。
         release: "1.0.1", // 你的 sourcemap 版本，和 sdk 的版本需要保持一致，可不填，默认为空
         appKey: "你的 API_KEY", // 从 sourcemap 管理 页面获取到的 Api Key，用于鉴权
         appSecret: "你的 API_TOKEN", // 从 sourcemap 管理 页面获取到的 Api token，用于鉴权
       }),
     ],
   }
   

（推荐，vite插件）使用@apm-insight-web/upload-sourcemaps构造vite插件使用

1. 在管理sourcemap页面的顶部，获取鉴权所需的API_KEY和API_TOKEN。
   
2. 执行以下命令，安装插件。您也可以选择全局安装。

npm install @apm-insight-web/upload-sourcemaps --save-dev

3. 使用@apm-insight-web/upload-sourcemaps构造vite插件

import { UploadSourcemapsCommand } from '@apm-insight-web/upload-sourcemaps'
import { Plugin } from 'vite'

interface Options {
  paths?: string[]
  app_id: string
  host?: string
  env?: string
  release?: string
  appSecret: string
  appKey: string
}

const uploadSourcemapsPlugin = function(options: Options): Plugin {
  return {
    name: 'vite-upload-sourcemaps-plugin',
    apply: 'build',
    closeBundle: async () => {
      let { paths } = options
      const { host, env, release, app_id, appSecret, appKey } = options
      if (!paths || !Array.isArray(paths) || !paths.length) {
        paths = ['./dist/assets']
      }
      try {
        await UploadSourcemapsCommand.upload({
          paths,
          app_id,
          host,
          env,
          release,
          appSecret,
          appKey,
        })
      // eslint-disable-next-line @typescript-eslint/no-unused-vars, no-empty
      } catch (e) {
      }
    },
  }
}

4. 在vite.config.ts中添加插件并使用。

export default defineConfig({
  plugins: [uploadSourcemapsPlugin({
      app_id: '123456',
      paths: ['./dist/assets'],  // 包含 sourcemap 文件的路径，我们会从中上传符号表文件到平台, 目前只支持单层目录。
      release: "1.0.1", // 你的 sourcemap 版本，和 sdk 的版本需要保持一致，可不填，默认为空
      appKey: "你的 API_KEY", // 从 sourcemap 管理 页面获取到的 Api Key，用于鉴权
      appSecret: "你的 API_TOKEN", // 从 sourcemap 管理 页面获取到的 Api token，用于鉴权
  })],
  build:{
    sourcemap:true
  }
})

使用upload-sourcemaps

1. 在管理sourcemap页面的顶部，获取鉴权所需的API_KEY和API_TOKEN。
   

2. 执行以下命令，安装插件。您也可以选择全局安装。

   npm install @apm-insight-web/upload-sourcemaps --save-dev
   

3. 使用插件。

   • 直接上传

     npx upload-sourcemaps --app_id xxxxxx --paths ./dir1 --app_key <API_KEY> --app_secret <API_TOKEN>
     

   • 指定release版本(非必须)
     release只能是常规字符串，最多支持下划线（_）做分隔的英文字符，不支持冒号（:）等特殊字符。

     npx upload-sourcemaps --app_id xxxxxx --paths ./dir1 --release 1.0.1 --app_key <API_KEY> --app_secret <API_TOKEN>
     

验证Sourcemap合法性

如果确认了已经上传Sourcemap，格式正确，release对应无误，但反解出来依旧不正确的。您可以采取如下方式自测。

1. 在平台下载对应Sourcemap。

   1. 在具体报错页面，找到报错的文件名，并检查是否有release信息。
      
   2. 单击管理sourcemap，然后在版本详情里的SourceMap管理模块，搜索对应文件名。
   3. 找到对应的Sourcemap文件，单击操作列的下载Sourcemap。
      

2. 下载mozilla官方Sourcemap反解库。
   下载地址：https://github.com/mozilla/source-map。

3. 使用如下脚本进行反解。

   var sourceMap = require("source-map");
   var fs = require("fs");
   // 此处替换为你下载下来的 sourcemap 文件
   let data = fs.readFileSync("../index.js.5d59fc.js.map").toString();
   const consumer = new sourceMap.SourceMapConsumer(data);
   consumer.then(c => {
     // 此处替换为原始报错的行列号
     const line = 23,
       column = 112003;
     let s = c.originalPositionFor({ line, column });
     console.log(s);
     console.log(`origin code for line: ${line}, ${column}\n`);
     console.log(
       `======================================================================`
     );
     console.log(
       c
         .sourceContentFor(s.source)
         .split("\n")
         .slice(Math.max(s.line - 10, 0), s.line + 10)
         .join(`\n`)
     );
     console.log(
       `======================================================================`
     );
   });
   

4. 检查输出结果。

   • 成功输出：成功输出应该能见到被反解出的原始代码。

     $   node   index.js
     origin   code   for   line:   373,   2432186
     ======================================================================
                 });
                 setTimeout(()   =>   {
                       throw   new   Error('local   test,   plz   ignore');
                 },   1000);
           },   []);
           return   (
                 <Provider   store={store}>
                       <Player   />
                 </Provider>
           );
     };
     ======================================================================
     

     自测结果正常，建议提交工单进行反馈。

   • 失败输出：失败输出的变量属性会全为null，且输出源代码报错。

     $   node   index.js
     {   source:   null,   line:   null,   column:   null,   name:   null   }
     origin   code   for   line:   373111,   2432186
     ======================================================================
     (node:4136)   UnhandledPromiseRejectionWarning:   Error:   "null"   is   not   in   the   SourceMap.
              ...
     

     自测结果也显示无法反解，说明Sourcemap或原始文件有误。请排查是否Sourcemap文件被覆盖，或者JS文件被二次处理。