没想到一个 source map 居然涉及到那么多知识盲区

Source map 想必大家都不陌生。线上的代码多是压缩后的，如果线上有报错却只能调试那个代码多半是个噩梦。因此我们需要有一个桥梁帮助我们搭建起源代码及压缩后代码的联系，source map 就是起了这个作用。

以下是 MDN 对于 source map 的解释：

调试原始源代码会比浏览器下载的转换后的代码更加容易。 source map[1] 是从已转换的代码映射到原始源的文件，使浏览器能够重构原始源并在调试器中显示重建的原始源。

但是不知道各位读者有没有对 source map 的原理产生过疑问？笔者列出了四个疑问，不知道各位是不是也存在过这样的问题：

Source map 四问

接下来的内容会逐步为读者解答这四问。

source map 文件是否影响网页性能

这个答案肯定是不会影响，否则构建相关的优化就肯定会涉及到对于 source map 的处理了，毕竟 source map 文件也不小。

其实 source map 只有在打开 dev tools 的情况下才会开始下载，相信大部分用户都不会去打开这个面板，所以这也就不是问题了。

这时可能会有读者想说：哎，但是我好像从来没有在 Network 里看到 source map 文件的加载呀？其实这只是浏览器隐藏了而已，如果大家使用抓包工具的话就能发现在打开 dev tools 的时候开始下载 source map 了。

source map 存在标准嘛？

source map 是存在一个标准的，为 Google 及 Mozilla 的工程师制定，文档地址[2]。正是因为存在这份标准，各个打包器及浏览器才能生成及使用 source map，否则就乱套了。

各个打包器基本都基于该库[3]来生成 source map，当然也存在一些魔改的方案，但是标准都是统一的。

通过上面的库生成出来的 source map 格式大致如下，大家也可以对比各个打包器的产物，格式及内容大部分都是一致的：

{ version: 3, file: "min.js", names: ["bar", "baz", "n"], sources: ["one.js", "two.js"], sourceRoot: "http://example.com/www/js/", mappings: "CAAC,IAAI,IAAM,SAAUA,GAClB,OAAOC,IAAID;CCDb,IAAI,IAAM,SAAUE,GAClB,OAAOA"}

接下来笔者介绍下重要字段的作用：

•version：顾名思义，指代了版本号，目前 source map 标准的版本为 3，也就是说这份 source map 使用的是第三版标准产出的•file：编译后的文件名•names：一个优化用的字段，后续会在 mappings 中用到•sources：多个源文件名•mappings：这是最重要的内容，表示了源代码及编译后代码的关系，但是先略过这块，下文中会详细解释

另外大部分应用都是由 webpack 来打包的，可能有些读者会发现 webpack 的 source map 产出的字段与上面的略微有些不一致。

这是因为 webpack 魔改了一些东西，但是底下还是基于这个库实现的，只是变动了一些不涉及核心的字段，具体代码[4]。

浏览器怎么知道源文件和 source map 的关系？

这里我们以 webpack 做个实验，通过 webpack5 对于以下代码进行打包：

// index.jsconst a = 1console.log(a);

当我们开启 source map 选项以后，产物应该为两个文件，分别为 bundle.js 以及 bundle.js.map。

查看 bundle.js 文件以后我们会发现代码中存在这一一段注释：

console.log(1);//# sourceMappingURL=bundle.js.map

sourceMappingURL 就是标记了该文件的 source map 地址。

当然除此之外还有别的方式，通过查阅 MDN 文档[5] 发现还可以通过 response header 的 SourceMap: <url> 字段来表明。

source map 是如何对应到源代码的？

这是 source map 最核心的功能，也是最涉及知识盲区的一块内容。

大家应该还记得上文中没介绍的 mapping 字段吧，接下来我们就来详细了解这个字段的用处。

我们还是以刚才打包的文件为例，来看看产出的 source map 长啥样（去掉了无关紧要的）：

{ sources:["webpack://webpack-source-demo/./src/index.js"], names: ['console', 'log'], mappings: 'AACAA,QAAQC,IADE',}

首先 mappings 的内容其实是 Base64 VLQ 的编码表示。

内容由三部分组成，分别为：

•英文，表示源码及压缩代码的位置关联•逗号，分隔一行代码中的内容。比如说 console.log(a) 就由 console 、log 及 a 三部分组成，所以存在两个逗号。•分号，代表换行

逗号和分号想必大家没啥疑问，但是对于这几个英文内容应该会很困惑。

其实这就是一种压缩数字内容的编码方式，毕竟源代码可能很庞大，用数字表示行数及列数的话 source map 文件将也会很庞大，因此选用 Base 64 来代表数字用以减少文件体积。

比如说 A 代表了数字 0，C 代表了数字 1 等等，有兴趣的读者可以通过该网站[6]了解映射关系。

了解了这层编码的映射关系，我们再来聊聊这一串串英文到底代表了什么。

其实这每串英文中的字母都代表了一个位置：

1.压缩代码的第几列2.哪个源代码文件，毕竟可以多个文件打包成一个，对应 sources 字段3.源代码第几行4.源代码第几列5.names 字段里的索引

这时读者可能有个疑惑，为啥没有压缩代码的第几行表示？这是因为压缩后的代码就一行，所以只需要表示第几列就行了。

更新：有读者询问 Base64 表达的数字是有上限的，如果需要表示的数字很大的话该怎么办。实际上除了每个分号中的第一串英文是用来表示代码的第几行第几列的绝对位置之外，后面的都是相对于之前的位置来做加减法的。

了解完以上知识以后，我们就来根据上文的内容解析下 AACAA 的具体含义吧，通过该网站[7]我们可以知道 AACAA 对应了 [0,0,1,0,0]，这里需要注意的是数字都从 0 开始，笔者表述的时候会自动加一，毕竟代码第零行听起来怪怪的。

1.压缩代码的第一列2.第一个源代码文件，也就是 index.js 文件了3.源代码第二行了4.源代码的第一列5.names 数组中的第一个索引，也就是 console

通过以上的解析，我们就能知道 console 在源代码及压缩文件中的具体位置了。

但是为什么 source map 会知道编译后的代码具体在什么位置呢？这里就要用到 AST 了。让我们打开网站[8]输入 console.log(a) 后观察右边的内容，你应该会发现如图所示的数据：

image-20210516214636867

因为 source map 是由 AST 产出的，所以我们能用上 AST 中的这个数据。

source map 的应用

一般来说 source map 的应用都是在监控系统中，开发者构建完应用后，通过插件将源代码及 source map 上传至平台中。一旦客户端上报错误后，我们就可以通过该库[9]来还原源代码的报错位置（具体 API 看文档即可），方便开发者快速定位线上问题。

最后

source map 是我们日常中经常用到的东西，但是直到学习这块内容的时候才知道居然涉及到了那么多的知识盲区。

大家如果有什么疑问欢迎在评论区交流。

引用链接

[1] source map: https://www.html5rocks.com/en/tutorials/developertools/sourcemaps/[2] 文档地址: https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit[3] 该库: https://github.com/mozilla/source-map[4] 具体代码: https://github.com/webpack/webpack-sources/blob/master/lib/SourceMapSource.js[5] MDN 文档: https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/SourceMap[6] 该网站: https://www.murzwin.com/base64vlq.html[7] 该网站: https://www.murzwin.com/base64vlq.html[8] 网站: https://astexplorer.net/[9] 该库: https://github.com/mozilla/source-map

彻底搞懂 Webpack 的 sourcemap 配置原理

用过 webpack 的都知道，webpack 的 sourcemap 配置是比较麻烦的，比如这两个配置的区别：

eval-nosources-cheap-module-source-map

hidden-module-source-map

是不是分不清楚？

其实它是有规律的。

你把配置写错的时候，webpack 会提示你一个正则：

^(inline-|hidden-|eval-)?(nosources-)?(cheap-(module-)?)?source-map$

这个就是配置的规律，是几种基础配置的组合。

搞懂了每一种基础配置，比如 eval、nosources、cheap、module，按照规律组合起来，也就搞懂了整体的配置。

那这每一种配置都是什么意思呢？

我们分别来看一下。

在讲基础配置之前，首先讲下 sourcemap 是什么：

sourcemap

sourcemap 是关联编译后的代码和源码的，通过一个个行列号的映射。

比如编译后代码的第 3 行第 4 列，对应着源码里的第 8 行第 5 列这种，这叫做一个 mapping。

sourcemap 的格式如下：

{

version : 3,

file: "out.js",

sourceRoot : "",

sources: ["foo.js", "bar.js"],

names: ["a", "b"],

mappings: "AAgBC,SAAQ,CAAEA;AAAEA",

sourcesContent: ['const a = 1; console.log(a)', 'const b = 2; console.log(b)']

}

version 是版本号，file 是文件名，sourceRoot 是源码根目录，names 是转换前的变量名，sources 是源码文件，sourcesContent 是每个 sources 对应的源码的内容，mappings 就是一个个位置映射了。

为什么 sources 可以有多个呢？

因为可能编译产物是多个源文件合并的，比如打包，一个 bundle.js 就对应了 n 个 sources 源文件。

为什么要把变量名单独摘出来到 names 里呢？

因为这样就可以通过下标来索引了，mapping 里面就不用保存变量名，只保留 names 的索引就行。

重点是 mappings 部分：

mappings 部分是通过分号; 和逗号 , 分隔的：

mappings:"AAAAA,BBBBB;CCCCC"

一个分号就代表一行，这样就免去了行的映射。

然后每一行可能有多个位置的映射，用 , 分隔。

那具体的每一个 mapping 都是啥呢？

比如 AAAAA 一共五位，分别有不同的含义：

第一位：转换后代码的第几列（行数通过分号 ; 来确定）

第二位：对应转换前的哪个源码文件，保存在 sources 里的，这里通过下标索引

第三位：对应转换前的源码的第几行

第四位：对应转换前的源码的第几列

第五位：对应转换前的源码的哪个变量名，保存在 names 里的，这里通过下标索引

然后经过编码之后，就成了 AAAAA 这种，这种编码方式叫做 VLQ 编码。

sourcemap 的格式还是很容易理解的，就是一一映射编译后代码的位置和源码的位置。

各种调试工具一般都支持 sourcemap 的解析，只要在文件末尾加上这样一行：

//@ sourceMappingURL=/path/to/source.js.map

运行时就会关联到源码：

sourcemap 介绍完了，接下来一起来看下 webpack 的几种 sourcemap 配置。

前面说过，webpack 的 sourcemap 配置是 eval、cheap、nosources、inline、source-map 等基础配置的组合。

我们先分别来看下这几种基础配置：

eval

eval 的 api 是动态执行 JS 代码的。比如：

但有个问题，eval 的代码打不了断点。

怎么解决这个问题呢？

浏览器支持了这样一种特性，只要在 eval 代码的最后加上 //# sourceURL=xxx，那就会以 xxx 为名字把这段代码加到 sources 里。那不就可以打断点了么？

比如这样：

执行以后，你会发现 sources 多了光.js的文件：

它是可以打断点的，比如在 add 里打个断点，然后再执行 eval。

你会发现它断住了！

除了指定 source 文件外，还可以进一步指定 sourcemap 来映射到源码：

这样，动态 eval 的代码也能关联到源码，并且能打断点了！

webpack 就利用了 eval 这个特性来优化的 sourcemap 生成的性能，比如你可以指定 devtool 为 eval：

生成的代码就是每个模块都被 eval 包裹的，并且有 sourceUrl 来指定文件名：

这样有啥好处呢？

快呀，因为只要指定个文件名就行，不用生成 sourcemap。sourcemap 的生成还是很慢的，要一个个 mapping 的处理，做编码之类的。

每个模块的代码都被 eval 包裹，那么执行的时候就会在 sources 里生成对应的文件，这样就可以打断点了：

不过这样只是把每个模块的代码分了出去，并没有做源码的关联，如果相关联源码，可以再开启 sourcemap：

你会发现生成的代码也是用 eval 包裹的，但除了 sourceUrl 外，还有 sourceMappingUrl：

再运行的时候除了 eval 的代码会生成文件放在 sources 外，还会做 sourcemap 的映射：

webpack 的 sourcemap 的配置就利用了浏览器对 eval 代码的调试支持。

所以为什么这个配置项不叫 sourcemap 而叫 devtool 呢？

因为不只是 sourcemap 呀，eval 的方式也行。

再来看下一个基础配置：

source-map

source-map 的配置是生成独立的 sourcemap 文件：

可以关联，也可以不关联，比如加上 hidden，就是生成 sourcemap 但是不关联：

生产环境就不需要关联 sourcemap，但是可能要生成 sourcemap 文件，把它上传到错误管理平台之类的，用来映射线上代码报错位置到对应的源码。

此外，还可以配置成 inline 的：

这个就是通过 dataUrl 的方式内联在打包后的文件里：

这几个配置还是很好懂的，我们来看下一个基础配置：

cheap

sourcemap 慢主要是处理映射比较慢，很多情况下我们不需要映射到源码的行和列，只要精确到行就行，这时候就可以用 cheap。

不精确到列能提升 souremap 生成速度，但是会牺牲一些精准度：

我们再来看下一个基础配置：

module

webpack 中对一个模块会进行多次处理，比如经过 loader A 做一次转换，再用 laoder B 做一次转换，之后打包到一起。

每次转换都会生成 sourcemap，那也就是有多个 sourcemap：

默认 sourcemap 只是能从 bundle 关联到模块的代码，也就是只关联了最后那个 sourcemap。

那如果你想调试最初的源码怎么办呢？

那就把每一次的 loader 的 sourcemap 也关联起来，这就是 module 配置的作用。

比如我们想调试 React 最初的源码，那就要先生成有 sourcemap 的代码：

怎么生成有 sourcemap 的 React 代码可以看我前面一篇文章。

有了 sourcemap 之后，要配置下 sourcemap-loader：

它的作用就是读取源码的 sourcemap，传递给后面的 loader。

之后配置 devtool，加上 module：

再次运行，你就会发现 react 代码能映射到最初的源码了：

之前只能从 bundle.js 映射到编译后的模块代码，也就是这一步：

devtool 配置加上 module，就支持了 loader 的 sourcemap 映射，然后再加上 sourmap-loader 来读取源码的 sourcemap，这样就能一次性映射回最初的源码：

当你想调试最初的源码的时候，module 的配置就很有用了。

接下来还有最后一个基础配置：

nosources

sourcemap 里是有 sourceContent 部分的，也就是直接把源码贴在这里，这样的好处是根据文件路径查不到文件也可以映射，但这样会增加 sourcemap 的体积。

如果你确定根据文件路径能查找到源文件，那不生成 sourceContent 也行。

比如 devtool 配置为 source-map，生成的 sourcemap 是这样的：

当你加上 nosources 之后，生成的 sourcemap 就没有 sourceContent 部分了：

sourcemap 文件大小会小很多。

基础配置讲完了，接下来就是各种组合了，这个就比较简单了，就算组合错了，webpack 也会提示你应该按照什么顺序来组合。

它是按照这个正则来校验的：^(inline-|hidden-|eval-)?(nosources-)?(cheap-(module-)?)?source-map$

接下来，我们讨论下最佳实践：

线上的时候当然要启用 hidden，不关联 sourcemap，但要生成 sourcemap，不大需要 module 来映射回最初的源码，所以可能是 hidden-source-map 这种。

开发的时候可以用 eval 的方式，这样是每个模块单独做映射，不用从 bundle.js 开始映射，然后 cheap 也可以开启，只映射到源码的某一行，提升生成速度，一般需要 module 来映射回最初的源码，所以可能是 eval-cheap-module-source-map 这种。

当然，具体怎么配置是按照需求来的，我们理解了每个基础配置，知道怎么组合就可以了。

不知道有没有同学会觉得这样写比较麻烦，能不能每个基础配置用 true、false 的方式配置呢？

确实可以，有这样一个插件：SourceMapDevToolPlugin

它有很多 option，比如 module、columns、noSources 等：

相当于是 devtool 的另一种配置方式，启用它需要把 devtool 设置为 false。

而且它可以控制更多东西，比如修改 sourcemap 的 url 和文件名等：

当你需要做更多的 sourcemap 生成方式的控制的时候，可以使用这个 webpack 插件。

总结

webpack 的 sourcemap 配置比较麻烦，但其实也是有规律的。

它是对一些基础配置按照一定顺序的组合，理解了每个基础配置，知道了怎么组合就理解了各种 devtool 配置。

eval：浏览器 devtool 支持通过 sourceUrl 来把 eval 的内容单独生成文件，还可以进一步通过 sourceMappingUrl 来映射回源码，webpack 利用这个特性来简化了 sourcemap 的处理，可以直接从模块开始映射，不用从 bundle 级别。

cheap：只映射到源代码的某一行，不精确到列，可以提升 sourcemap 生成速度

source-map：生成 sourcemap 文件，可以配置 inline，会以 dataURL 的方式内联，可以配置 hidden，只生成 sourcemap，不和生成的文件关联

nosources：不生成 sourceContent 内容，可以减小 sourcemap 文件的大小

module：sourcemap 生成时会关联每一步 loader 生成的 sourcemap，配合 sourcemap-loader 可以映射回最初的源码

理解了这些基础配置项，根据 ^(inline-|hidden-|eval-)?(nosources-)?(cheap-(module-)?)?source-map$ 的规律来进行组合，就可以实现各种需求下的 sourcemap 配置。

当然，这种 sourcemap 配置还不够细致，比如 sourcemap 的 url 怎么生成，文件名是什么。如果想对这些做配置，可以关掉 devtool，启用 SourceMapDevToolPlugin 来配置。

虽然 webapck 的 sourcemap 配置方式比较多，但最底层也就是浏览器支持的文件级别的 sourcemap 还有 eval 代码的 source 映射和 sourcemap 这两种机制。其余的方式都是基于这两种机制的封装。

理解了浏览器 devtool的机制，webpack 封装出的基础配置，知道了组合规则，就可以应对各种需求的 sourcemap 配置。

相关问答

MapSource是一款由Garmin公司开发的地图管理软件,可以用来规划路线和管理导航设备中的地图数据。具体使用教程可以分为以下几个步骤:1.安装MapSource软件并连...

你可以安装win7的中文补丁。或者通过windowsupdate下载和安装简体中文语言包,更改系统显示语言为简体中文。请首先确保计算机可以连接到互联网络,点击开始按...

一个接口接手持GPS,一个接口接电脑,配合mapsource进行数据的上传下载请注意,您需要安装适当的驱动程序和软件才能将eTrex设备连接到电脑上。您可以在Garmin官...

应该是gps手簿输入坐标,其方法如下:1、直接打开GPS,设置好地图参数(将位置格式设置成UTM)后,利用GPS的“存点”功能将点位输入保存。2、稍好一点的办法是...

GPX是数据交换格式,用googleearth、mapsource和GISoffice可以打开。GPX文件是一种通用的地图信息文件,可被各种导航仪和地图软件识别,在GPX中,一个没有顺序...

1、直接打开GPS,设置好地图参数(将位置格式设置成UTM)后,利用GPS的“存点”功能将点位输入保存。2、稍好一点的办法是,在MapSource中,利用“航点工具”一...

GPX是数据交换格式,能打开它的软件很多,你可以上网搜一下,我知道的googleearth、mapsource和GISoffice都可以打开,后两个软件还可以对其进行编辑,且这些软...

与手持机连接Garmin60CSX具备MiniUSB数据接口,使用数据线与安装好MapSource的机器连接起来,这里需要注意提前准备好GARMINUSB驱动程序,在官方网站或者随机...

如下代码所示: 能分享下工作中那些你觉得好用的软件吗?

分享一款好用的办公软件,这是一款协同办公软件,可以大大提升工作效率。办公,其实更多的是信息的传递,办公是侧重于信息的传递与协同,如果是高频次、有严谨...需...