gulp經常使用插件之gulp-sourcemaps使用

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