Webpack Loader 高手進階(二)

文章首發於我的github blog: Biu-blog，歡迎你們關注~

Webpack 系列文章：

Webpack Loader 高手進階（一）
Webpack Loader 高手進階（二）
Webpack Loader 高手進階（三）

---

Webpack Loader 詳解

上篇文章主要講了 loader 的配置，匹配相關的機制。這篇主要會講當一個 module 被建立以後，使用 loader 去處理這個 module 內容的流程機制。首先咱們來整體的看下整個的流程：

在 module 一開始構建的過程當中，首先會建立一個 loaderContext 對象，它和這個 module 是一一對應的關係，而這個 module 所使用的全部 loaders 都會共享這個 loaderContext 對象，每一個 loader 執行的時候上下文就是這個 loaderContext 對象，因此能夠在咱們寫的 loader 裏面經過 this 來訪問。

// NormalModule.js

const { runLoaders } = require('loader-runner')

class NormalModule extends Module {
  ...
  createLoaderContext(resolver, options, compilation, fs) {
    const requestShortener = compilation.runtimeTemplate.requestShortener;
    // 初始化 loaderContext 對象，這些初始字段的具體內容解釋在文檔上有具體的解釋(https://webpack.docschina.org/api/loaders/#this-data)
        const loaderContext = {
            version: 2,
            emitWarning: warning => {...},
            emitError: error => {...},
            exec: (code, filename) => {...},
            resolve(context, request, callback) {...},
            getResolve(options) {...},
            emitFile: (name, content, sourceMap) => {...},
            rootContext: options.context, // 項目的根路徑
            webpack: true,
            sourceMap: !!this.useSourceMap,
            _module: this,
            _compilation: compilation,
            _compiler: compilation.compiler,
            fs: fs
        };

    // 觸發 normalModuleLoader 的鉤子函數，開發者能夠利用這個鉤子來對 loaderContext 進行拓展
        compilation.hooks.normalModuleLoader.call(loaderContext, this);
        if (options.loader) {
            Object.assign(loaderContext, options.loader);
        }

        return loaderContext;
  }

  doBuild(options, compilation, resolver, fs, callback) {
    // 建立 loaderContext 上下文
        const loaderContext = this.createLoaderContext(
            resolver,
            options,
            compilation,
            fs
    )
    
    runLoaders(
      {
        resource: this.resource, // 這個模塊的路徑
                loaders: this.loaders, // 模塊所使用的 loaders
                context: loaderContext, // loaderContext 上下文
                readResource: fs.readFile.bind(fs) // 讀取文件的 node api
      },
      (err, result) => {
        // do something
      }
    )
  }
  ...
}

當 loaderContext 初始化完成後，開始調用 runLoaders 方法，這個時候進入到了 loaders 的執行階段。runLoaders 方法是由loader-runner這個獨立的 npm 包提供的方法，那咱們就一塊兒來看下 runLoaders 方法內部是如何運行的。

首先根據傳入的參數完成進一步的處理，同時對於 loaderContext 對象上的屬性作進一步的拓展：

exports.runLoaders = function runLoaders(options, callback) {
  // read options
    var resource = options.resource || ""; // 模塊的路徑
    var loaders = options.loaders || []; // 模塊所須要使用的 loaders
    var loaderContext = options.context || {}; // 在 normalModule 裏面建立的 loaderContext
    var readResource = options.readResource || readFile;

    var splittedResource = resource && splitQuery(resource);
    var resourcePath = splittedResource ? splittedResource[0] : undefined; // 模塊實際路徑
    var resourceQuery = splittedResource ? splittedResource[1] : undefined; // 模塊路徑 query 參數
    var contextDirectory = resourcePath ? dirname(resourcePath) : null; // 模塊的父路徑

    // execution state
    var requestCacheable = true;
    var fileDependencies = [];
    var contextDependencies = [];

    // prepare loader objects
    loaders = loaders.map(createLoaderObject); // 處理 loaders 

  // 拓展 loaderContext 的屬性
    loaderContext.context = contextDirectory;
    loaderContext.loaderIndex = 0; // 當前正在執行的 loader 索引
    loaderContext.loaders = loaders;
    loaderContext.resourcePath = resourcePath;
    loaderContext.resourceQuery = resourceQuery;
    loaderContext.async = null; // 異步 loader
  loaderContext.callback = null;

  ...

  // 須要被構建的模塊路徑，將 loaderContext.resource -> getter/setter
  // 例如 /abc/resource.js?rrr
  Object.defineProperty(loaderContext, "resource", {
        enumerable: true,
        get: function() {
            if(loaderContext.resourcePath === undefined)
                return undefined;
            return loaderContext.resourcePath + loaderContext.resourceQuery;
        },
        set: function(value) {
            var splittedResource = value && splitQuery(value);
            loaderContext.resourcePath = splittedResource ? splittedResource[0] : undefined;
            loaderContext.resourceQuery = splittedResource ? splittedResource[1] : undefined;
        }
  });

  // 構建這個 module 全部的 loader 及這個模塊的 resouce 所組成的 request 字符串
  // 例如：/abc/loader1.js?xyz!/abc/node_modules/loader2/index.js!/abc/resource.js?rrr
    Object.defineProperty(loaderContext, "request", {
        enumerable: true,
        get: function() {
            return loaderContext.loaders.map(function(o) {
                return o.request;
            }).concat(loaderContext.resource || "").join("!");
        }
  });
  // 在執行 loader 提供的 pitch 函數階段傳入的參數之一，剩下還未被調用的 loader.pitch 所組成的 request 字符串
    Object.defineProperty(loaderContext, "remainingRequest", {
        enumerable: true,
        get: function() {
            if(loaderContext.loaderIndex >= loaderContext.loaders.length - 1 && !loaderContext.resource)
                return "";
            return loaderContext.loaders.slice(loaderContext.loaderIndex + 1).map(function(o) {
                return o.request;
            }).concat(loaderContext.resource || "").join("!");
        }
  });
  // 在執行 loader 提供的 pitch 函數階段傳入的參數之一，包含當前 loader.pitch 所組成的 request 字符串
    Object.defineProperty(loaderContext, "currentRequest", {
        enumerable: true,
        get: function() {
            return loaderContext.loaders.slice(loaderContext.loaderIndex).map(function(o) {
                return o.request;
            }).concat(loaderContext.resource || "").join("!");
        }
  });
  // 在執行 loader 提供的 pitch 函數階段傳入的參數之一，包含已經被執行的 loader.pitch 所組成的 request 字符串
    Object.defineProperty(loaderContext, "previousRequest", {
        enumerable: true,
        get: function() {
            return loaderContext.loaders.slice(0, loaderContext.loaderIndex).map(function(o) {
                return o.request;
            }).join("!");
        }
  });
  // 獲取當前正在執行的 loader 的query參數
  // 若是這個 loader 配置了 options 對象的話，this.query 就指向這個 option 對象
  // 若是 loader 中沒有 options，而是以 query 字符串做爲參數調用時，this.query 就是一個以 ? 開頭的字符串
    Object.defineProperty(loaderContext, "query", {
        enumerable: true,
        get: function() {
            var entry = loaderContext.loaders[loaderContext.loaderIndex];
            return entry.options && typeof entry.options === "object" ? entry.options : entry.query;
        }
  });
  // 每一個 loader 在 pitch 階段和正常執行階段均可以共享的 data 數據
    Object.defineProperty(loaderContext, "data", {
        enumerable: true,
        get: function() {
            return loaderContext.loaders[loaderContext.loaderIndex].data;
        }
  });
  
  var processOptions = {
        resourceBuffer: null, // module 的內容 buffer
        readResource: readResource
  };
  // 開始執行每一個 loader 上的 pitch 函數
    iteratePitchingLoaders(processOptions, loaderContext, function(err, result) {
    // do something...
  });
}

這裏稍微總結下就是在 runLoaders 方法的初期會對相關參數進行初始化的操做，特別是將 loaderContext 上的部分屬性改寫爲 getter/setter 函數，這樣在不一樣的 loader 執行的階段能夠動態的獲取一些參數。

接下來開始調用 iteratePitchingLoaders 方法執行每一個 loader 上提供的 pitch 函數。你們寫過 loader 的話應該都清楚，每一個 loader 能夠掛載一個 pitch 函數，每一個 loader 提供的 pitch 方法和 loader 實際的執行順序正好相反。這塊的內容在 webpack 文檔上也有詳細的說明(請戳我)。

這些 pitch 函數並非用來實際處理 module 的內容的，主要是能夠利用 module 的 request，來作一些攔截處理的工做，從而達到在 loader 處理流程當中的一些定製化的處理須要，有關 pitch 函數具體的實戰能夠參見下一篇文檔[Webpack 高手進階-loader 實戰] TODO: 連接

function iteratePitchingLoaders() {
  // abort after last loader
    if(loaderContext.loaderIndex >= loaderContext.loaders.length)
        return processResource(options, loaderContext, callback);

  // 根據 loaderIndex 來獲取當前須要執行的 loader
    var currentLoaderObject = loaderContext.loaders[loaderContext.loaderIndex];

  // iterate
  // 若是被執行過，那麼直接跳過這個 loader 的 pitch 函數
    if(currentLoaderObject.pitchExecuted) {
        loaderContext.loaderIndex++;
        return iteratePitchingLoaders(options, loaderContext, callback);
    }

    // 加載 loader 模塊
    // load loader module
    loadLoader(currentLoaderObject, function(err) {
        // do something ...
    });
}

每次執行 pitch 函數前，首先根據 loaderIndex 來獲取當前須要執行的 loader (currentLoaderObject)，調用 loadLoader 函數來加載這個 loader，loadLoader 內部兼容了 SystemJS，ES Module，CommonJs 這些模塊定義，最終會將 loader 提供的 pitch 方法和普通方法賦值到 currentLoaderObject 上：

// loadLoader.js
module.exports = function (loader, callback) {
  ...
  var module = require(loader.path)
 
  ...
  loader.normal = module

  loader.pitch = module.pitch

  loader.raw = module.raw

  callback()
  ...
}

當 loader 加載完後，開始執行 loadLoader 的回調：

loadLoader(currentLoaderObject, function(err) {
  var fn = currentLoaderObject.pitch; // 獲取 pitch 函數
  currentLoaderObject.pitchExecuted = true;
  if(!fn) return iteratePitchingLoaders(options, loaderContext, callback); // 若是這個 loader 沒有提供 pitch 函數，那麼直接跳過

  // 開始執行 pitch 函數
  runSyncOrAsync(
    fn,
    loaderContext, [loaderContext.remainingRequest, loaderContext.previousRequest, currentLoaderObject.data = {}],
    function(err) {
      if(err) return callback(err);
      var args = Array.prototype.slice.call(arguments, 1);
      // Determine whether to continue the pitching process based on
      // argument values (as opposed to argument presence) in order
      // to support synchronous and asynchronous usages.
      // 根據是否有參數返回來判斷是否向下繼續進行 pitch 函數的執行
      var hasArg = args.some(function(value) {
        return value !== undefined;
      });
      if(hasArg) {
        loaderContext.loaderIndex--;
        iterateNormalLoaders(options, loaderContext, args, callback);
      } else {
        iteratePitchingLoaders(options, loaderContext, callback);
      }
    }
  );
})

這裏出現了一個 runSyncOrAsync 方法，放到後文去講，開始執行 pitch 函數，當 pitch 函數執行完後，執行傳入的回調函數。咱們看到回調函數裏面會判斷接收到的參數的個數，除了第一個 err 參數外，若是還有其餘的參數(這些參數是 pitch 函數執行完後傳入回調函數的)，那麼會直接進入 loader 的 normal 方法執行階段，而且會直接跳事後面的 loader 執行階段。若是 pitch 函數沒有返回值的話，那麼進入到下一個 loader 的 pitch 函數的執行階段。讓咱們再回到 iteratePitchingLoaders 方法內部，當全部 loader 上面的 pitch 函數都執行完後，即 loaderIndex 索引值 >= loader 數組長度的時候：

function iteratePitchingLoaders () {
  ...

  if(loaderContext.loaderIndex >= loaderContext.loaders.length)
    return processResource(options, loaderContext, callback);

  ...
}

function processResource(options, loaderContext, callback) {
    // set loader index to last loader
    loaderContext.loaderIndex = loaderContext.loaders.length - 1;

    var resourcePath = loaderContext.resourcePath;
    if(resourcePath) {
        loaderContext.addDependency(resourcePath); // 添加依賴
        options.readResource(resourcePath, function(err, buffer) {
            if(err) return callback(err);
            options.resourceBuffer = buffer;
            iterateNormalLoaders(options, loaderContext, [buffer], callback);
        });
    } else {
        iterateNormalLoaders(options, loaderContext, [null], callback);
    }
}

在 processResouce 方法內部調用 node API readResouce 讀取 module 對應路徑的文本內容，調用 iterateNormalLoaders 方法，開始進入 loader normal 方法的執行階段。

function iterateNormalLoaders () {
  if(loaderContext.loaderIndex < 0)
        return callback(null, args);

    var currentLoaderObject = loaderContext.loaders[loaderContext.loaderIndex];

    // iterate
    if(currentLoaderObject.normalExecuted) {
        loaderContext.loaderIndex--;
        return iterateNormalLoaders(options, loaderContext, args, callback);
    }

    var fn = currentLoaderObject.normal;
    currentLoaderObject.normalExecuted = true;
    if(!fn) {
        return iterateNormalLoaders(options, loaderContext, args, callback);
    }

  // buffer 和 utf8 string 之間的轉化
    convertArgs(args, currentLoaderObject.raw);

    runSyncOrAsync(fn, loaderContext, args, function(err) {
        if(err) return callback(err);

        var args = Array.prototype.slice.call(arguments, 1);
        iterateNormalLoaders(options, loaderContext, args, callback);
    });
}

在 iterateNormalLoaders 方法內部就是依照從右到左的順序(正好與 pitch 方法執行順序相反)依次執行每一個 loader 上的 normal 方法。loader 無論是 pitch 方法仍是 normal 方法的執行可爲同步的，也可設爲異步的(這裏說下 normal 方法的)。通常若是你寫的 loader 裏面可能涉及到計算量較大的狀況時，可將你的 loader 異步化，在你 loader 方法裏面調用this.async方法，返回異步的回調函數，當你 loader 內部實際的內容執行完後，可調用這個異步的回調來進入下一個 loader 的執行。

module.exports = function (content) {
  const callback = this.async()
  someAsyncOperation(content, function(err, result) {
    if (err) return callback(err);
    callback(null, result);
  });
}

除了調用 this.async 來異步化 loader 以外，還有一種方式就是在你的 loader 裏面去返回一個 promise，只有當這個 promise 被 resolve 以後，纔會調用下一個 loader(具體實現機制見下文)：

module.exports = function (content) {
  return new Promise(resolve => {
    someAsyncOpertion(content, function(err, result) {
      if (err) resolve(err)
      resolve(null, result)
    })
  })
}

這裏還有一個地方須要注意的就是，上下游 loader 之間的數據傳遞過程當中，若是下游的 loader 接收到的參數爲一個，那麼能夠在上一個 loader 執行結束後，若是是同步就直接 return 出去：

module.exports = function (content) {
  // do something
  return content
}

若是是異步就直接調用異步回調傳遞下去(參見上面 loader 異步化)。若是下游 loader 接收的參數多於一個，那麼上一個 loader 執行結束後，若是是同步那麼就須要調用 loaderContext 提供的 callback 函數:

module.exports = function (content) {
  // do something
  this.callback(null, content, argA, argB)
}

若是是異步的仍是繼續調用異步回調函數傳遞下去(參見上面 loader 異步化)。具體的執行機制涉及到上文還沒講到的 runSyncOrAsync 方法，它提供了上下游 loader 調用的接口：

function runSyncOrAsync(fn, context, args, callback) {
    var isSync = true; // 是否爲同步
    var isDone = false;
    var isError = false; // internal error
    var reportedError = false;
    // 給 loaderContext 上下文賦值 async 函數，用以將 loader 異步化，並返回異步回調
    context.async = function async() {
        if(isDone) {
            if(reportedError) return; // ignore
            throw new Error("async(): The callback was already called.");
        }
        isSync = false; // 同步標誌位置爲 false
        return innerCallback;
  };
  // callback 的形式能夠向下一個 loader 多個參數
    var innerCallback = context.callback = function() {
        if(isDone) {
            if(reportedError) return; // ignore
            throw new Error("callback(): The callback was already called.");
        }
        isDone = true;
        isSync = false;
        try {
            callback.apply(null, arguments);
        } catch(e) {
            isError = true;
            throw e;
        }
    };
    try {
        // 開始執行 loader
        var result = (function LOADER_EXECUTION() {
            return fn.apply(context, args);
    }());
    // 若是爲同步的執行
        if(isSync) {
      isDone = true;
      // 若是 loader 執行後沒有返回值，執行 callback 開始下一個 loader 執行
            if(result === undefined)
        return callback();
      // loader 返回值爲一個 promise 實例，待這個實例被resolve或者reject後執行下一個 loader。這也是 loader 異步化的一種方式
            if(result && typeof result === "object" && typeof result.then === "function") {
                return result.catch(callback).then(function(r) {
                    callback(null, r);
                });
      }
      // 若是 loader 執行後有返回值，執行 callback 開始下一個 loader 執行
            return callback(null, result);
        }
    } catch(e) {
        // do something
    }
}

以上就是對於 module 在構建過程當中 loader 執行流程的源碼分析。可能平時在使用 webpack 過程瞭解相關的 loader 執行規則和策略，再配合這篇對於內部機制的分析，應該會對 webpack loader 的使用有更加深入的印象。

文章首發於我的github blog: Biu-blog，歡迎你們關注~