SourceMap 使用教程 & Source Map入门教程 & JavaScript Source Map 详解

SourceMap 使用教程 & Source Map入门教程 & JavaScript Source Map 详解

https://www.jianshu.com/p/ebf0ca8febb2

https://www.cnblogs.com/fundebug/p/learn-source-map.html

http://www.ruanyifeng.com/blog/2013/01/javascript_source_map.html

1. 前言

SourceMap 一个存储源代码与编译代码对应位置映射的信息文件

在前端的工作中主要是用来解决以下三个方面出现的 debug 问题：

a. 代码压缩混淆后
b. 利用 sass 、typeScript 等其他语言编译成 css 或 JS 后
c. 利用 webpack 等打包工具进行多文件合并后

上面三种情况，我们在调试时都是没办法像调试源码般轻松，这就需要 SourceMap 帮助我们在控制台中转换成源码，从而进行 debug 。

---

2. 原理

实际上就是一个 JSON 键值对，利用 VLQ编码与特定的规则存储位置信息。
这里面的逻辑有兴趣的可以看看阮老师的这篇文章《 JavaScript Source Map 详解 》

　　{
　　　　version : 3,        //Source map的版本
　　　　file: "out.js",      //转换后的文件名
　　　　sourceRoot : "",   //转换前的文件所在的目录。如果与转换前的文件在同一目录，该项为空
　　　　sources: ["foo.js", "bar.js"],   //转换前的文件。该项是一个数组，表示可能存在多个文件合并
　　　　names: ["src", "maps", "are", "fun"],   //转换前的所有变量名和属性名
　　　　mappings: "AAgBC,SAAQ,CAAEA"  //记录位置信息的字符串
　　}

其实不用懂原理直接使用就好，毕竟 .map 文件也是工具生成的，不用自己编写。

---

3. 使用方法

这东西因为是 Google 开发出来的，所以目前只有 chrome 能够运行

环境设置

进入开发者模式的设置中

开发者模式

找到 Sources 栏，勾选上允许 JS SourceMap 与 css SourceMap （默认应该是选上的）

Sources

.map 文件生成

生成 .map 文件有很多种方法，除了使用 Google 自己的 Closure编译器 外，还有 Gulp 、 Grunt 等工具可以利用。本人项目中是利用 Gulp 来生成 .map 的，下面就具体讲讲 .map 在 Gulp 中的使用 （不会 Gulp 可以看看我这篇文章 《 Node.js 自动化工具 - Gulp 》）

在 Gulp 中是利用 gulp-sourcemaps 这一插件实现的，首先看一个例子：

var gulp = require('gulp');
var plugin1 = require('gulp-plugin1');
var plugin2 = require('gulp-plugin2');
var sourcemaps = require('gulp-sourcemaps');

gulp.task('javascript', function() {
  gulp.src('src/**/*.js')
    .pipe(sourcemaps.init())  //标记 map 记录始发点
      .pipe(plugin1())    //其他任务插件运行
      .pipe(plugin2())      //其他任务插件运行
    .pipe(sourcemaps.write())  //输出 .map 文件
    .pipe(gulp.dest('dist'));  
});

上面代码逻辑是会把 .map 的 JSON 变成数据流的形式写在该文件中，当你打开原文件时可以看到这样的一段注释：

//# sourceMappingURL=http://192.168.0.118:8080/app/dist/maps/common/js/version.js.map

这段表明对应的 .map 文件地址，如果是数据流地址将会变成流字符串，这样我们就可以在 chrome 中打开调试啦

SourceMap 使用

先自己做一个带 .map 的，经过 uglify() 压缩后的 js 文件后，我们再来看看怎么利用

打开开发者模式后，在 Sources 中会看看类似于上图的窗口，解释一下这三个感叹号说明的东西：

1. chrome 的 workspace 模块，它提供了一个空间可以将本地文件放入 chrome 中并在浏览器调试代码时，同时将本地文件代码一并修改。

2. 格式化该压缩文件吗？点击 more 你会看到其用法，在该窗口最下面 {} 的按钮，点一下将会格式化压缩代码。可以看到其参数名等都是简化后的，也是不利于 debug 的。（要是找到关联 .map 文件会直接显示 common.js:formatted）

3. 这个就是引入 .map 文件进行 debug 啦，按 Ctrl + P 按照注释所提供的 .map 地址找到你想要 debug 的源码文件。这时候你就能在源码中断点调试了！

---

4. gulp-sourcemaps API 详解

如上诉这种简单的 .map 使用方法是满足不了开发需求的。

上面是一个压缩的需求，.map 应该分开，不能跟在源文件中，不然压缩后比压缩前都要大了，这时候我们需要了解更多的 API 用法。

官档有点乱，我按照自己的思路整理了一下：

1. sourcemaps.init()
2. sourcemaps.write()
3. sourcemaps.mapSources()
4. sourcemaps.identityMap()

下面围绕着这四个 API 逐个讲解，而 gulp.src() 与 gulp.dest() 用法就看我那篇 Gulp 的文章就可以了。

sourcemaps.init()

如字面意思是 sourcemaps 的初始化 API ，其中的配置项：

sourcemaps.init({
      loadMaps: true,  //是否加载以前的 .map 
      largeFile: true,   //是否以流的方式处理大文件
})

sourcemaps.write()

sourcemaps. write( url , {option} ) 的输出配置 API

url

sourcemaps.write( 'maps' )
填写相对于 gulpfile.js 的 url 地址，用于存放 .map 文件

{option} 

sourcemaps.write('maps', {
      addComment: false,   //为源文件添加 .map 地址注释，当你设为 false 时则禁用注释（比如你想要通过 header 加载映射源）
      includeContent：false,  //默认情况下，源映射包括源代码，通过false来使用原始文件（目测没什么用）
      sourceRoot: url , //配合上面的 includeContent：false ；指定原始文件位置
      sourceRoot: function(file) {
         return '/src';   //同时支持方法函数
      },
      destPath: url,  //指定另外的输出地址，可以不靠 gulp.dist() 输出
      sourceMappingURLPrefix: url ,   //在编写外部源映射时，指定前缀到源映射URL上,相对路径将把它们的主要点去掉（非常有用），也就是改变那个注释的 URL 前缀。
      sourceMappingURL: function(file){ ,   //如果您需要完全控制源映射URL，您可以传递函数到此选项。函数的输出必须是源映射的完整URL(在输出文件的函数中)。
          return ;
      }，
      mapFile:  function(mapFilePath) {     //重名 .map 文件
        // source map files are named *.map instead of *.js.map
        return mapFilePath.replace('.js.map', '.map');
      },
      charset: utf8 ,    //指定编码格式
      clone : {deep:false,contents:false}    //克隆原始原件，并用克隆文件来创建映射文件，参数参照 file.clone()  
})

sourcemaps.mapSources()

赋予更多定义 source path 的方式

sourcemaps.mapSources(function(sourcePath, file) {
        return '../src/' + sourcePath;   //为原文件地址提供前缀，该应该场景应该是，当你所使用的插件需要生产别的文件
})

我自己试验了一下，好像没什么作用，并没有改变源地址，也没改变输出地址，你们参照下官档描述自己试验一下吧

The exported mapSources method gives full control over the source paths. It takes a function that is called for every source and receives the default source path as a parameter and the original vinyl file.

sourcemaps.identityMap()

一个只为了 JS 和 CSS 能产生完整映射的 SourceMap ，相对于默认的空源 SourceMap 更能防止信息丢失。

gulp.task('javascript', function() {
  var stream = gulp.src('src/**/*.js')
    .pipe(sourcemaps.init())
      // An identity sourcemap will be generated at this step
      .pipe(sourcemaps.identityMap())
      .pipe(plugin1())
      .pipe(plugin2())
    .pipe(sourcemaps.write('../maps')
    .pipe(gulp.dest('public/scripts'));
});

---

5. gulp-sourcemaps 可用插件

gulp-sourcemaps 并不是所有的插件都能够像上面那样使用的，需要先查看它支持的 wiki page

目前支持三大类：

1. Generic
2. JS
3. CSS

当然你也可以直接添加插件支持，使用 vinyl-sourcemaps-apply ，目前本人还没有研究过制作插件，所以现在就不详解了，以后有机会再说

好了，上面就是 《 SourceMap 使用教程 》的全部内容了，希望能够对你有所帮助，如有疑问欢迎留言~

作者：Max_Law
链接：https://www.jianshu.com/p/ebf0ca8febb2
來源：简书
著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。

------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Source Map入门教程

部署前端之前，开发者通常会对代码进行打包压缩，这样可以减少代码大小，从而有效提高访问速度。然而，压缩代码的报错信息是很难Debug的，因为它的行号和列号已经失真。这时就需要Source Map来还原真实的出错位置了。

为啥变换代码？

前端代码越来越复杂的情况下，开发者通常会使用webpack、UglifyJS2等工具对代码进行打包变换，这样可以减少代码大小，有效提高访问速度。关于变换代码的原因，这里不妨引用一下大神阮一峰的JavaScript Source Map 详解:

• 压缩，减小体积。比如jQuery 1.9的源码，压缩前是252KB，压缩后是32KB。
• 多个文件合并，减少HTTP请求数。
• 其他语言编译成JavaScript。最常见的例子就是CoffeeScript。

如何变换代码？

下面是一个简单的“hello World”程序hello.js

function sayHello() { var name = "Fundebug"; var greeting = "Hello, " + Name; console.log(greeting); } sayHello();

使用UglifyJS2对源代码进行压缩变换:

uglifyjs hello.js \
         -m toplevel=true \
         -c unused=true,collapse_vars=true \ -o hello.min.js

压缩后的代码hello.min.js

function o(){var o="Hello, "+Name;console.log(o)}o();

为啥需要Source Map?

使用Firefox执行hello.js的报错信息是这样:

ReferenceError: Name is not defined
    sayHello file:///Users/fundebug/sourcemap-tutorial/hello.js:4:9 <匿名> file:///Users/fundebug/sourcemap-tutorial/hello.js:8:1

而hello.min.js的报错信息是这样:

ReferenceError: Name is not defined
    o file:///Users/fundebug/sourcemap-tutorial/hello.min.js:1:18 <匿名> file:///Users/fundebug/sourcemap-tutorial/hello.min.js:1:59

对比压缩前后的出错信息，我们会发现，错误行号和列号已经失真，且函数名也经过了变换。而对于真实的前端项目，开发者会将数十个源文件压缩为一个文件，这时，错误的列号可能多达数千，且出错的真实文件名也是很难确定的，这样的话，压缩代码的报错信息是很难Debug的。

而Source Map则可以用于还原真实的出错位置，帮助开发者更快的Debug。

什么是Source Map?

使用UglifyJS2时指定source-map选项即可生成Source Map:

uglifyjs hello.js \
         -m toplevel=true \
         -c unused=true,collapse_vars=true \ --source-map hello.min.js.map \ --source-map-include-sources \ --source-map-root \ -o hello.min.js

各种主流前端任务管理工具，打包工具都支持生成Source Map，具体可以查看生成Source Map - Fundebug文档。

生成的hello.min.js多了sourceMappingURL，表示Source Map文件的位置。

function o(){var o="Hello, "+Name;console.log(o)}o(); //# sourceMappingURL=hello.min.js.map

生成的Source Map为hello.min.js.map:

{
    "version": 3,
    "sources": ["hello.js"],
    "names": ["sayHello", "greeting", "Name", "console", "log"], "mappings": "AAAA,QAASA,KAEL,GACIC,GAAW,UAAYC,IAC3BC,SAAQC,IAAIH,GAGhBD", "file": "hello.min.js", "sourceRoot": "", "sourcesContent": ["function sayHello()\n{\n var name = \"Fundebug\";\n var greeting = \"Hello, \" + Name;\n console.log(greeting);\n}\n\nsayHello();\n"] }

由hello.min.js.map可知，Source Map是一个JSON文件，而它包含了代码转换前后的位置信息。也就是说，给定一个转换之后的压缩代码的位置，就可以通过Source Map获取转换之前的代码位置，反过来也一样。Source Map各个属性的含义如下:

• version：Source Map的版本号。
• sources：转换前的文件列表。
• names：转换前的所有变量名和属性名。
• mappings：记录位置信息的字符串，经过编码。
• file：(可选)转换后的文件名。
• sourceRoot：(可选)转换前的文件所在的目录。如果与转换前的文件在同一目录，该项为空。
• sourcesContent:(可选)转换前的文件内容列表，与sources列表依次对应。

Source Map真正神奇之处在于mappings属性，它记录了位置是如何对应的。JavaScript Source Map 详解已经有很好的解释，这里不再赘述。

怎样使用Source Map?

主流浏览器均支持Source Map功能，不过Chrome与Firefox需要一些简单的配置，具体步骤请参考How to enable source maps。下面以MacBook上的Chrome浏览器为例，介绍一下配置方法:

1. 开启开发者工具

使用快捷键option + command + i；或者在菜单栏选择视图->开发者->开发者工具

 

2. 打开设置

使用快捷键fn + F1；或者点击右上角的三个点的图标，选择Settings

 

3. 开启Source Map

在Sources中，选中Enable JavaScript source maps

 

为了测试，我写了一个简单的HTML文件hello.min.html

<head>
    <script type="text/javascript" src="hello.min.js"></script> </head>

使用Chrome打开hello.min.html，在控制台看到的错误如下:

Uncaught ReferenceError: Name is not defined at o (hello.min.js:1) at hello.min.js:1

报错的文件仍然为hello.min.js，需要刷新一下Source Map才有作用:

Uncaught ReferenceError: Name is not defined
    at o (hello.js:4)
    at hello.js:8

注意，Chrome的报错信息没有列号，因此4为错误的行号。Chrome不仅可以通过Source Map还原真实的出错位置，还可以根据Source Map的sourcesContent还原出错的源代码。点击出错位置，即可跳转到源码，这样Debug将非常方便。

 

参考链接

• Source Map 入门教程
• JavaScript Source Map 详解
• Source Map Revision 3 Proposal
• How to enable source maps

-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

作者： 阮一峰

日期： 2013年1月23日

上周，jQuery 1.9发布。

这是2.0版之前的最后一个新版本，有很多新功能，其中一个就是支持Source Map。

访问 http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js，打开压缩后的版本，滚动到底部，你可以看到最后一行是这样的：

　　//@ sourceMappingURL=jquery.min.map

这就是Source Map。它是一个独立的map文件，与源码在同一个目录下，你可以点击进去，看看它的样子。

这是一个很有用的功能，本文将详细讲解这个功能。

一、从源码转换讲起

JavaScript脚本正变得越来越复杂。大部分源码（尤其是各种函数库和框架）都要经过转换，才能投入生产环境。

常见的源码转换，主要是以下三种情况：

　　（1）压缩，减小体积。比如jQuery 1.9的源码，压缩前是252KB，压缩后是32KB。

　　（2）多个文件合并，减少HTTP请求数。

　　（3）其他语言编译成JavaScript。最常见的例子就是CoffeeScript。

这三种情况，都使得实际运行的代码不同于开发代码，除错（debug）变得困难重重。

通常，JavaScript的解释器会告诉你，第几行第几列代码出错。但是，这对于转换后的代码毫无用处。举例来说，jQuery 1.9压缩后只有3行，每行3万个字符，所有内部变量都改了名字。你看着报错信息，感到毫无头绪，根本不知道它所对应的原始位置。

这就是Source map想要解决的问题。

二、什么是Source map

简单说，Source map就是一个信息文件，里面储存着位置信息。也就是说，转换后的代码的每一个位置，所对应的转换前的位置。

有了它，出错的时候，除错工具将直接显示原始代码，而不是转换后的代码。这无疑给开发者带来了很大方便。

目前，暂时只有Chrome浏览器支持这个功能。在Developer Tools的Setting设置中，确认选中"Enable source maps"。

三、如何启用Source map

正如前文所提到的，只要在转换后的代码尾部，加上一行就可以了。

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

map文件可以放在网络上，也可以放在本地文件系统。

四、如何生成Source map

最常用的方法是使用Google的Closure编译器。

生成命令的格式如下：

　　java -jar compiler.jar \ 
　　　　--js script.js \
　　　　--create_source_map ./script-min.js.map \
　　　　--source_map_format=V3 \
　　　　--js_output_file script-min.js

各个参数的意义如下：

　　- js： 转换前的代码文件
　　- create_source_map： 生成的source map文件
　　- source_map_format：source map的版本，目前一律采用V3。
　　- js_output_file： 转换后的代码文件。

其他的生成方法可以参考这篇文章。

五、Source map的格式

打开Source map文件，它大概是这个样子：

　　{
　　　　version : 3,
　　　　file: "out.js",
　　　　sourceRoot : "",
　　　　sources: ["foo.js", "bar.js"],
　　　　names: ["src", "maps", "are", "fun"],
　　　　mappings: "AAgBC,SAAQ,CAAEA"
　　}

整个文件就是一个JavaScript对象，可以被解释器读取。它主要有以下几个属性：

　　- version：Source map的版本，目前为3。

　　- file：转换后的文件名。

　　- sourceRoot：转换前的文件所在的目录。如果与转换前的文件在同一目录，该项为空。

　　- sources：转换前的文件。该项是一个数组，表示可能存在多个文件合并。

　　- names：转换前的所有变量名和属性名。

　　- mappings：记录位置信息的字符串，下文详细介绍。

六、mappings属性

下面才是真正有趣的部分：两个文件的各个位置是如何一一对应的。

关键就是map文件的mappings属性。这是一个很长的字符串，它分成三层。

　　第一层是行对应，以分号（;）表示，每个分号对应转换后源码的一行。所以，第一个分号前的内容，就对应源码的第一行，以此类推。

　　第二层是位置对应，以逗号（,）表示，每个逗号对应转换后源码的一个位置。所以，第一个逗号前的内容，就对应该行源码的第一个位置，以此类推。

　　第三层是位置转换，以VLQ编码表示，代表该位置对应的转换前的源码位置。

举例来说，假定mappings属性的内容如下：

　　mappings:"AAAAA,BBBBB;CCCCC"

就表示，转换后的源码分成两行，第一行有两个位置，第二行有一个位置。

七、位置对应的原理

每个位置使用五位，表示五个字段。

从左边算起，

　　- 第一位，表示这个位置在（转换后的代码的）的第几列。

　　- 第二位，表示这个位置属于sources属性中的哪一个文件。

　　- 第三位，表示这个位置属于转换前代码的第几行。

　　- 第四位，表示这个位置属于转换前代码的第几列。

　　- 第五位，表示这个位置属于names属性中的哪一个变量。

有几点需要说明。首先，所有的值都是以0作为基数的。其次，第五位不是必需的，如果该位置没有对应names属性中的变量，可以省略第五位。再次，每一位都采用VLQ编码表示；由于VLQ编码是变长的，所以每一位可以由多个字符构成。

如果某个位置是AAAAA，由于A在VLQ编码中表示0，因此这个位置的五个位实际上都是0。它的意思是，该位置在转换后代码的第0列，对应sources属性中第0个文件，属于转换前代码的第0行第0列，对应names属性中的第0个变量。

八、VLQ编码

最后，谈谈如何用VLQ编码表示数值。

这种编码最早用于MIDI文件，后来被多种格式采用。它的特点就是可以非常精简地表示很大的数值。

VLQ编码是变长的。如果（整）数值在-15到+15之间（含两个端点），用一个字符表示；超出这个范围，就需要用多个字符表示。它规定，每个字符使用6个两进制位，正好可以借用Base 64编码的字符表。

在这6个位中，左边的第一位（最高位）表示是否"连续"（continuation）。如果是1，代表这６个位后面的6个位也属于同一个数；如果是0，表示该数值到这6个位结束。

　　Continuation
　　|　　　　　Sign
　　|　　　　　|
　　V　　　　　V
　　１０１０１１

这6个位中的右边最后一位（最低位）的含义，取决于这6个位是否是某个数值的VLQ编码的第一个字符。如果是的，这个位代表"符号"（sign），0为正，1为负（Source map的符号固定为0）；如果不是，这个位没有特殊含义，被算作数值的一部分。

九、VLQ编码：实例

下面看一个例子，如何对数值16进行VLQ编码。

　　第一步，将16改写成二进制形式10000。

　　第二步，在最右边补充符号位。因为16大于0，所以符号位为0，整个数变成100000。

　　第三步，从右边的最低位开始，将整个数每隔5位，进行分段，即变成1和00000两段。如果最高位所在的段不足5位，则前面补0，因此两段变成00001和00000。

　　第四步，将两段的顺序倒过来，即00000和00001。

　　第五步，在每一段的最前面添加一个"连续位"，除了最后一段为0，其他都为1，即变成100000和000001。

　　第六步，将每一段转成Base 64编码。

查表可知，100000为g，000001为B。因此，数值16的VLQ编码为gB。上面的过程，看上去好像很复杂，做起来其实很简单，具体的实现请看官方的base64-vlq.js文件，里面有详细的注释。

十、参考链接

　　- Introduction To JavaScript Source Maps
　　- Source Map Revision 3 Proposal

（完）

文档信息

• 版权声明：自由转载-非商用-非衍生-保持署名（创意共享3.0许可证）
• 发表日期： 2013年1月23日
• 更多内容： 档案 » JavaScript
• 文集：《前方的路》，《未来世界的幸存者》
• 社交媒体： twitter， weibo