loader API

所谓 loader 只是一个导出为函数的 JavaScript 模块。loader runner 会调用这个函数，然后把上一个 loader 产生的结果或者资源文件(resource file)传入进去。函数的 this 上下文将由 webpack 填充，并且 loader runner 具有一些有用方法，可以使 loader 改变为异步调用方式，或者获取 query 参数。

第一个 loader 的传入参数只有一个：资源文件(resource file)的内容。compiler 需要得到最后一个 loader 产生的处理结果。这个处理结果应该是 String 或者 Buffer（被转换为一个 string），代表了模块的 JavaScript 源码。另外还可以传递一个可选的 SourceMap 结果（格式为 JSON 对象）。

如果是单个处理结果，可以在同步模式中直接返回。如果有多个处理结果，则必须调用 this.callback()。在异步模式中，必须调用 this.async()，来指示 loader runner 等待异步结果，它会返回 this.callback() 回调函数，随后 loader 必须返回 undefined 并且调用该回调函数。

示例

以下部分提供了不同类型的 loader 的一些基本示例。注意，map 和 meta 参数是可选的，查看下面的 this.callback。

同步 loader

无论是 return 还是 this.callback 都可以同步地返回转换后的 content 内容：

sync-loader.js

  1. module.exports = function(content, map, meta) {
  2.   return someSyncOperation(content);
  3. };

this.callback 方法则更灵活，因为它允许传递多个参数，而不仅仅是content。

sync-loader-with-multiple-results.js

  1. module.exports = function(content, map, meta) {
  2.   this.callback(null, someSyncOperation(content), map, meta);
  3.   return; // 当调用 callback() 时总是返回 undefined
  4. };

异步 loader

对于异步 loader，使用 this.async 来获取 callback 函数：

async-loader.js

  1. module.exports = function(content, map, meta) {
  2.   var callback = this.async();
  3.   someAsyncOperation(content, function(err, result) {
  4.     if (err) return callback(err);
  5.     callback(null, result, map, meta);
  6.   });
  7. };

async-loader-with-multiple-results.js

  1. module.exports = function(content, map, meta) {
  2.   var callback = this.async();
  3.   someAsyncOperation(content, function(err, result, sourceMaps, meta) {
  4.     if (err) return callback(err);
  5.     callback(null, result, sourceMaps, meta);
  6.   });
  7. };

loader 最初被设计为可以在同步 loader pipeline（如 Node.js ，使用 enhanced-require），_以及_在异步 pipeline（如 webpack ）中运行。然而在 Node.js 这样的单线程环境下进行耗时长的同步计算不是个好主意，我们建议尽可能地使你的 loader 异步化。但如果计算量很小，同步 loader 也是可以的。

“Raw” loader

默认情况下，资源文件会被转化为 UTF-8 字符串，然后传给 loader。通过设置 raw，loader 可以接收原始的 Buffer。每一个 loader 都可以用 String 或者 Buffer 的形式传递它的处理结果。Complier 将会把它们在 loader 之间相互转换。

raw-loader.js

  1. module.exports = function(content) {
  2.   assert(content instanceof Buffer);
  3.   return someSyncOperation(content);
  4.   // 返回值也可以是一个 `Buffer`
  5.   // 即使不是 raw loader 也没问题
  6. };
  7. module.exports.raw = true;

越过 loader(Pitching loader)

loader 总是从右到左地被调用。有些情况下，loader 只关心 request 后面的元数据(metadata)，并且忽略前一个 loader 的结果。在实际（从右到左）执行 loader 之前，会先从左到右调用 loader 上的 pitch 方法。对于以下 use 配置：

  1. module.exports = {
  2.   //...
  3.   module: {
  4.     rules: [
  5.       {
  6.         //...
  7.         use: [
  8.           'a-loader',
  9.           'b-loader',
  10.           'c-loader'
  11.         ]
  12.       }
  13.     ]
  14.   }
  15. };

将会发生这些步骤：

  1. |- a-loader `pitch`
  2.   |- b-loader `pitch`
  3.     |- c-loader `pitch`
  4.       |- requested module is picked up as a dependency
  5.     |- c-loader normal execution
  6.   |- b-loader normal execution
  7. |- a-loader normal execution

那么，为什么 loader 可以利用 “跳跃(pitching)” 阶段呢？

首先，传递给 pitch 方法的 data，在执行阶段也会暴露在 this.data 之下，并且可以用于在循环时，捕获和共享前面的信息。

  1. module.exports = function(content) {
  2.   return someSyncOperation(content, this.data.value);
  3. };
  5. module.exports.pitch = function(remainingRequest, precedingRequest, data) {
  6.   data.value = 42;
  7. };

其次，如果某个 loader 在 pitch 方法中给出一个结果，那么这个过程会回过身来，并跳过剩下的 loader。在我们上面的例子中，如果 b-loader 的 pitch 方法返回了一些东西：

  1. module.exports = function(content) {
  2.   return someSyncOperation(content);
  3. };
  5. module.exports.pitch = function(remainingRequest, precedingRequest, data) {
  6.   if (someCondition()) {
  7.     return 'module.exports = require(' + JSON.stringify('-!' + remainingRequest) + ');';
  8.   }
  9. };

上面的步骤将被缩短为：

  1. |- a-loader `pitch`
  2.   |- b-loader `pitch` returns a module
  3. |- a-loader normal execution

查看 bundle-loader，了解如何以更有意义的方式使用此过程。

loader 上下文

loader context 表示在 loader 内使用 this 可以访问的一些方法或属性。

假设我们这样请求加载别的模块： 在 /abc/file.js 中：

  1. require('./loader1?xyz!loader2!./resource?rrr');

this.version

loader API 的版本号。目前是 2。这对于向后兼容性有一些用处。通过这个版本号，你可以为不同版本间的破坏性变更编写不同的逻辑，或做降级处理。

this.context

模块所在的目录。可以用作解析其他模块路径的上下文。

在我们的例子中：这个属性为 /abc，因为 resource.js 在这个目录中

this.rootContext

从 webpack 4 开始，原先的 this.options.context 被改进为 this.rootContext。

this.request

被解析出来的 request 字符串。

在我们的例子中："/abc/loader1.js?xyz!/abc/node_modules/loader2/index.js!/abc/resource.js?rrr"

this.query

NaN. 如果这个 loader 配置了 options 对象的话，this.query 就指向这个 option 对象。 NaN. 如果 loader 中没有 options，而是以 query 字符串作为参数调用时，this.query 就是一个以 ? 开头的字符串。

使用 loader-utils 中提供的 getOptions 方法 来提取给定 loader 的 option。

this.callback

一个可以同步或者异步调用的可以返回多个结果的函数。预期的参数是：

  1. this.callback(
  2.   err: Error | null,
  3.   content: string | Buffer,
  4.   sourceMap?: SourceMap,
  5.   meta?: any
  6. );

NaN. 第一个参数必须是 Error 或者 null NaN. 第二个参数是一个 string 或者 Buffer。 NaN. 可选的：第三个参数必须是一个可以被这个模块解析的 source map。 NaN. 可选的：第四个选项，会被 webpack 忽略，可以是任何东西（例如一些元数据）。

可以将抽象语法树(abstract syntax tree - AST)（例如 ESTree）作为第四个参数（meta），如果你想在多个 loader 之间共享通用的 AST，这样做有助于加速编译时间。

如果这个函数被调用的话，你应该返回 undefined 从而避免含糊的 loader 结果。

this.async

告诉 loader-runner 这个 loader 将会异步地回调。返回 this.callback。

this.data

在 pitch 阶段和正常阶段之间共享的 data 对象。

this.cacheable

设置是否可缓存标志的函数：

  1. cacheable(flag = true: boolean)

默认情况下，loader 的处理结果会被标记为可缓存。调用这个方法然后传入 false，可以关闭 loader 的缓存。

一个可缓存的 loader 在输入和相关依赖没有变化时，必须返回相同的结果。这意味着 loader 除了 this.addDependency 里指定的以外，不应该有其它任何外部依赖。

this.loaders

所有 loader 组成的数组。它在 pitch 阶段的时候是可以写入的。

  1. loaders = [{request: string, path: string, query: string, module: function}]

在我们的示例中：

  1. [
  2.   {
  3.     request: '/abc/loader1.js?xyz',
  4.     path: '/abc/loader1.js',
  5.     query: '?xyz',
  6.     module: [Function]
  7.   },
  8.   {
  9.     request: '/abc/node_modules/loader2/index.js',
  10.     path: '/abc/node_modules/loader2/index.js',
  11.     query: '',
  12.     module: [Function]
  13.   }
  14. ];

this.loaderIndex

当前 loader 在 loader 数组中的索引。

在我们的示例中：loader1 中得到：0，loader2 中得到：1

this.resource

request 中的资源部分，包括 query 参数。

在我们的示例中："/abc/resource.js?rrr"

this.resourcePath

资源文件的路径。

在我们的示例中："/abc/resource.js"

this.resourceQuery

资源的 query 参数。

在我们的示例中："?rrr"

this.target

编译的目标。从配置选项中传递过来的。

示例："web", "node"

this.webpack

如果是由 webpack 编译的，这个布尔值会被设置为真。

loader 最初被设计为可以同时当 Babel transform 用。如果你编写了一个 loader 可以同时兼容二者，那么可以使用这个属性了解是否存在可用的 loaderContext 和 webpack 特性。

this.sourceMap

应该生成一个 source map。因为生成 source map 可能会非常耗时，你应该确认 source map 确实有必要请求。

this.emitWarning

  1. emitWarning(warning: Error)

发出一个警告，在输出中显示如下：

  1. WARNING in ./src/lib.js (./src/loader.js!./src/lib.js)
  2. Module Warning (from ./src/loader.js):
  3. Here is a Warning!
  4.  @ ./src/index.js 1:0-25

Note that the warnings will not be displayed if stats.warnings is set to false, or some other omit setting is used to stats such as none or errors-only. See the stats configuration.

this.emitError

  1. emitError(error: Error)

发出一个错误，在输出中显示如下：

  1. ERROR in ./src/lib.js (./src/loader.js!./src/lib.js)
  2. Module Error (from ./src/loader.js):
  3. Here is an Error!
  4.  @ ./src/index.js 1:0-25

Unlike throwing an Error directly, it will NOT interrupt the compilation process of the current module.

this.loadModule

  1. loadModule(request: string, callback: function(err, source, sourceMap, module))

解析给定的 request 到一个模块，应用所有配置的 loader ，并且在回调函数中传入生成的 source 、sourceMap 和 模块实例（通常是 NormalModule 的一个实例）。如果你需要获取其他模块的源代码来生成结果的话，你可以使用这个函数。

this.resolve

  1. resolve(context: string, request: string, callback: function(err, result: string))

像 require 表达式一样解析一个 request 。

this.addDependency

  1. addDependency(file: string)
  2. dependency(file: string) // 简写

加入一个文件作为产生 loader 结果的依赖，使它们的任何变化可以被监听到。例如，html-loader 就使用了这个技巧，当它发现 src 和 src-set 属性时，就会把这些属性上的 url 加入到被解析的 html 文件的依赖中。

this.addContextDependency

  1. addContextDependency(directory: string)

把文件夹作为 loader 结果的依赖加入。

this.clearDependencies

  1. clearDependencies()

移除 loader 结果的所有依赖。甚至自己和其它 loader 的初始依赖。考虑使用 pitch。

this.emitFile

  1. emitFile(name: string, content: Buffer|string, sourceMap: {...})

产生一个文件。这是 webpack 特有的。

this.fs

用于访问 compilation 的 inputFileSystem 属性。

废弃的上下文属性

强烈建议不要使用这些属性，因为我们打算移除它们。它们仍然列在此处用于文档目的。

this.exec

  1. exec(code: string, filename: string)

以模块的方式执行一些代码片段。如果需要，请查看这里的评论以获取替换方法。

this.resolveSync

  1. resolveSync(context: string, request: string) -> string

像 require 表达式一样解析一个 request。

this.value

向下一个 loader 传值。如果你知道了作为模块执行后的结果，请在这里赋值（以单元素数组的形式）。

this.inputValue

从上一个 loader 那里传递过来的值。如果你会以模块的方式处理输入参数，建议预先读入这个变量（为了性能因素）。

this.options

options 属性，在 webpack 3 中已经废弃(deprecated)，在 webpack 4 中已经移除(removed)。

this.debug

一个布尔值，当处于 debug 模式时为 true。

this.minimize

决定处理结果是否应该被压缩。

this._compilation

一种 hack 写法。用于访问 webpack 的 Compilation 对象。

this._compiler

一种 hack 写法。用于访问 webpack 的 Compiler 对象。

this._module

一种 hack 写法。用于访问当前加载的 Module 对象。

Error Reporting

You can report errors from inside a loader by:

  • Using this.emitError. Will report the errors without interrupting module’s compilation.
  • Using throw (or other uncaught exception). Throwing an error while a loader is running will cause current module compilation failure.
  • Using callback (in async mode). Pass an error to the callback will also cause module compilation failure.

For example:

./src/index.js

  1. require('./loader!./lib');

Throwing an error from loader:

./src/loader.js

  1. module.exports = function(source) {
  2.   throw new Error('This is a Fatal Error!');
  3. };

Or pass an error to the callback in async mode:

./src/loader.js

  1. module.exports = function(source) {
  2.   const callback = this.async();
  3.   //...
  4.   callback(new Error('This is a Fatal Error!'), source);
  5. };

The module will get bundled like this:

  1. /***/ "./src/loader.js!./src/lib.js":
  2. /*!************************************!*\
  3.   !*** ./src/loader.js!./src/lib.js ***!
  4.   \************************************/
  5. /*! no static exports found */
  6. /***/ (function(module, exports) {
  8. throw new Error("Module build failed (from ./src/loader.js):\nError: This is a Fatal Error!\n    at Object.module.exports (/workspace/src/loader.js:3:9)");
  10. /***/ })

Then the build output will also display the error (Similar to this.emitError):

  1. ERROR in ./src/lib.js (./src/loader.js!./src/lib.js)
  2. Module build failed (from ./src/loader.js):
  3. Error: This is a Fatal Error!
  4.     at Object.module.exports (/workspace/src/loader.js:2:9)
  5.  @ ./src/index.js 1:0-25

As you can see below, not only error message, but also details about which loader and module are involved:

  • the module path: ERROR in ./src/lib.js
  • the request string: (./src/loader.js!./src/lib.js)
  • the loader path: (from ./src/loader.js)
  • the caller path: @ ./src/index.js 1:0-25

The loader path in the error is displayed since webpack 4.12

All the errors and warnings will be recorded into stats. Please see Stats Data.

Inline matchResource

A new inline request syntax was introduced in webpack v4. Prefixing <match-resource>!=! to a request will set the matchResource for this request.

It is not recommended to use this syntax in application code. Inline request syntax is intended to only be used by loader generated code. Not following this recommendation will make your code webpack-specific and non-standard.

A relative matchResource will resolve relative to the current context of the containing module.

When a matchResource is set, it will be used to match with the module.rules instead of the original resource. This can be useful if further loaders should be applied to the resource, or if the module type need to be changed. It’s also displayed in the stats and used for matching Rule.issuer and test in splitChunks.

Example:

file.js

  1. /* STYLE: body { background: red; } */
  2. console.log('yep');

A loader could transform the file into the following file and use the matchResource to apply the user-specified CSS processing rules:

file.js (transformed by loader)

  1. import './file.js.css!=!extract-style-loader/getStyles!./file.js';
  2. console.log('yep');

This will add a dependency to extract-style-loader/getStyles!./file.js and treat the result as file.js.css. Because module.rules has a rule matching /\.css$/ and it will apply to this dependency.

The loader could look like this:

extract-style-loader/index.js

  1. const stringifyRequest = require('loader-utils').stringifyRequest;
  2. const getRemainingRequest = require('loader-utils').getRemainingRequest;
  3. const getStylesLoader = require.resolve('./getStyle');
  5. module.exports = function (source) {
  6.   if (STYLES_REGEXP.test(source)) {
  7.     source = source.replace(STYLES_REGEXP, '');
  8.     const remReq = getRemainingRequest(this);
  9.     return `import ${stringifyRequest(`${this.resource}.css!=!${getStylesLoader}!${remReq}`)};${source}`;
  10.   }
  11.   return source;
  12. };

extract-style-loader/getStyles.js

  1. module.exports = function(source) {
  2.   const match = STYLES_REGEXP.match(source);
  3.   return match[0];
  4. };

贡献人员

EugeneHlushko EugeneHlushko TheLarkInn TheLarkInn byzyk byzyk jantimon jantimon jhnns jhnns sokra sokra tbroadley tbroadley