gulp常用插件之gulp-sourcemaps使用

Posted 2020-11-23 jiaoshou

更多gulp常用插件使用请访问：gulp常用插件汇总

---

gulp-sourcemaps这是一款用来生成映射文件的一个插件，SourceMap 文件记录了一个存储源代码与编译代码对应位置映射的信息文件。我们在调试时都是没办法像调试源码般轻松，这就需要 SourceMap 帮助我们在控制台中转换成源码，从而进行 debug。

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

1. 代码压缩混淆后

1. 利用 sass 、typeScript 等其他语言编译成 css 或 JS 后
2. 利用 webpack 等打包工具进行多文件合并后

gulp-sourcemaps 目前支持三大类：

• Generic
• JS
• CSS

更多使用文档请点击访问gulp-sourcemaps工具官网。

安装

一键安装不多解释

npm install --save-dev gulp-sourcemaps

原理

实际上就是一个 JSON 键值对，利用 VLQ编码与特定的规则存储位置信息。

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

使用

编写内联源映射到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=data:application/json;charset=utf8;base64,eyJ2ZXJzaW9uIjozLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIiwic291cmNlcyI6WyJhLmpzIl0sInNvdXJjZXNDb250ZW50IjpbIlxuXG5sZXQgeGlhb21pbmcgPSAneG0nXG5sZXQgemhhbmdzYW4gPSAnenMnXG5sZXQgbGlzaSA9ICdscydcbmxldCBmaXZlID0gJydcbmNvbnN0IGhhaGEgPSAxMFxuXG5mdW5jdGlvbiBhZGQoKXtcbiAgXG4gIGNvbnNvbGUubG9nKCdsb2cgYWRkIGZpdmUgLS0tLScsZml2ZSlcblxuICByZXR1cm4gZml2ZSA9IHpoYW5nc2FuICsgbGlzaVxufVxuXG5hZGQoKVxuY29uc29sZS5sb2coJ2xvZyBmaXZlIC0tLS0nLGZpdmUpXG5cbmZpdmUgKz0gaGFoYVxuXG5jb25zb2xlLmxvZygnbG9nIGZpdmUrKyAtLS0tJyxmaXZlKVxuXG5jb25zb2xlLmxvZygnYS5qcycpXG5cbiJdLCJmaWxlIjoiYS5qcyJ9

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

gulp-sourcemaps API 详解
如上诉这种简单的 .map 使用方法是满足不了开发需求的。上面是一个压缩的需求，.map 应该分开，不能跟在源文件中，不然压缩后比压缩前都要大了。

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

sourcemaps.init()

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

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

• loadMaps
  设置为true以加载源文件的现有地图。支持以下内容：
  • 内联源地图
  • sourceMappingURL=注释引用的源地图文件
  • 同一目录中具有相同名称（加上.map）的源地图文件
• identityMap
  不建议使用此选项。建议升级使用sourcemap.identityMap API。

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来使用原始文件。推荐包含内容，因为它“有效”。设置为`false`时，您必须托管源文件并设置正确的`sourceRoot`。 
      sourceRoot: url , //配合上面的 includeContent：false ；指定原始文件位置。这通常是URL（或绝对URL路径），而不是本地文件系统路径。默认情况下，源根目录是''，或者在`destPath`设置了大小写的情况下，从源映射到源基本目录的相对路径（这在许多开发环境中都应适用）。如果使用相对路径（空字符串或以a开头.的路径），则将其解释为相对于目标的路径。该插件将其重写为相对于每个源映射的路径。
      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;   //为原文件地址提供前缀，该应该场景应该是，当你所使用的插件需要生产别的文件
})

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'));
});