从零实现一个 Webpack Loader

2,960 阅读6分钟

参考:

  • Webpack Book --- Extending with Loaders。
  • Webpack Doc --- Loader Interface

Loader 是 Webpack 几大重要的模块之一。当你需要加载资源,就需要设置对应的 Loader,这样就可以对其源代码进行转换。

由于 Webpack 社区的繁荣,使得大部分的业务场景所使用的资源都有对用的 loader,可以参考官网的 available loaders,但是由于业务的独特性,也可能没有适用的 loader。

接下来会通过几个示例来让你学会如何开发一个自己的 loader。但在此之前,最好先了解如何单独调试它们。

利用 loader-runner 调试 Loaders

loader-runner 允许你不依靠 webpack 单独运行 loader,首先安装它

mkdir loader-runner-example
npm init
npm install loader-runner --save-dev

接下来,创建一个 demo-loader,来进行测试

mkdir loaders
echo "module.exports = input => input + input;" > loaders/demo-loader.js

这个 loader 会将引入模块的内容复制一次并返回。创建所引入的模块

echo "Hello world" > demo.txt

接下来,通过loader-runner运行加载器:

// 创建 run-loader.js
const fs = require("fs");
const path = require("path");
const { runLoaders } = require("loader-runner");

runLoaders(
  {
    resource: "./demo.txt",
    loaders: [path.resolve(__dirname, "./loaders/demo-loader")],
    readResource: fs.readFile.bind(fs),
  },
  (err, result) => 
    (err ? console.error(err) : console.log(result))
);

当你运行 node run-loader.js,会看到终端上 log 出来

{ result: [ 'Hello world\nHello world\n' ],
  resourceBuffer: <Buffer 48 65 6c 6c 6f 20 77 6f 72 6c 64 0a>,
  cacheable: true,
  fileDependencies: [ './demo.txt' ],
  contextDependencies: [] }

从输出结果中可以看出

  • result:loader 完成了,我们赋予它的任务,将目标模块的内容复制了一边;
  • resourceBuffer:模块内容被转换为了 Buffer。

如果,需要将转换后的文件输出出来,只需要修改 runLoaders 的第二个参数,如

runLoaders(
  {
    resource: "./demo.txt",
    loaders: [path.resolve(__dirname, "./loaders/demo-loader")],
    readResource: fs.readFile.bind(fs),
  },
  (err, result) => {
    if (err) console.error(err)
    
    fs.writeFileSync("./output.txt", result.result)
  }
);

开发一个异步的 Loader

尽管你可以通过上述这种同步式接口(synchronous interface)实现一系列的 loader,但是这种形式并不能适用所有场景,例如将第三方软件包包装为 loader 时就会强制要求你执行此操作。

为了将上述例子调整为异步的形式,我们使用 webpack 提供的 this.async() API。通过调用这个函数可以返回一个遵守 Node 规范的回调函数(error first,result second)。

上述例子可以改写为:

loaders/demo-loader.js

module.exports = function(input) {
  const callback = this.async();

  // No callback -> return synchronous results
  // if (callback) { ... }

  callback(null, input + input);
};

webpack 通过 this 进行注入,所以不能使用 () => {}。

之后运行 node run-loader.js 会在终端上打印出相同的结果。如果你想要在对 loader 执行期间产生的异常进行处理,则可以

module.exports = function(input) {
  const callback = this.async();

  callback(new Error("Demo error"));
};

终端上打印的日志会包含错误:demo error,堆栈跟踪显示错误发生的位置。

仅返回输出

loader 也可以用于单独输出代码,可以这样实现

module.exports = function() {
  return "foobar";
};

为什么要这么做呢?你可以将 webpack 的入口文件传递给 loader。来代替指向预先设定的文件的情况,这样可以动态地生成对应 code 的 loader。

如果你想要 return 一个 Buffer 形式的输出,可以设定 module.exports.raw = true,将原有的 string 改为 buffer。

写入文件

有一些 loader,像 file-loader,会生成文件。对此 webpack 提供了一个方法,this.emitFile,但是 loader-runner 暂时还不支持,所以需要主动实现

runLoaders(
  {
    resource: "./demo.txt",
    loaders: [path.resolve(__dirname, "./loaders/demo-loader")],
	// 为 this 添加 emitFile method
    context: {
      emitFile: () => {},
    },

    readResource: fs.readFile.bind(fs),
  },
  (err, result) => (err ? console.error(err) : console.log(result))
);

要实现 file-loader 的基本思想,您必须做两件事:找出文件并返回它的路径。 你可以按如下方式实现:

const loaderUtils = require("loader-utils");

module.exports = function(content) {
  const url = loaderUtils.interpolateName(this, "[hash].[ext]", {
    content,
  });

  this.emitFile(url, content);

  const path = `__webpack_public_path__ + ${JSON.stringify(url)};`;

  return `export default ${path}`;
};

Webpack 提供了额外的两个 emit 方法:

  • this.emitWarning(<string>)
  • this.emitError(<string>)

这些方法都是用来替代控制台。 与 this.emitFile 一样,你必须模拟它们才能使loader-runner工作。

接下来的问题是,如何将文件名传递给 loader。

传递配置给 loader

为了将所需的配置传递给 loader,我们需要做一些修改

run-loader.js

const fs = require("fs");
const path = require("path");
const { runLoaders } = require("loader-runner");

runLoaders(
  {
    resource: "./demo.txt",

    loaders: [
      {
        loader: path.resolve(__dirname, "./loaders/demo-loader"),
        options: {
          name: "demo.[ext]",
        },
      },
    ],

    context: {
      emitFile: () => {},
    },
      
    readResource: fs.readFile.bind(fs),
  },
  (err, result) => (err ? console.error(err) : console.log(result))
);

可以看到,我们将 loaders 从原有的

loaders: [path.resolve(__dirname, "./loaders/demo-loader")]

改为了,从而可以传递 options

loaders: [
      {
        loader: path.resolve(__dirname, "./loaders/demo-loader"),
        options: {
          name: "demo.[ext]",
        },
      },
    ]

为了能够获取到,我们传递的 options,依然利用 loader-utils 来解析 options。

别忘了 npm install loader-utils --save-dev

为了将它与 loader 进行连接

loaders/demo-loader.js

const loaderUtils = require("loader-utils");

module.exports = function(content) {
  // 获取 options
  const { name } = loaderUtils.getOptions(this);


  const url = loaderUtils.interpolateName(this, "[hash].[ext]", {
    content,
  });


  const url = loaderUtils.interpolateName(this, name, { content });
  );
};

运行 node run-loader.js,你会发现在终端上打印出了

{ result:
   [ 'export default __webpack_public_path__ + "f0ef7081e1539ac00ef5b761b4fb01b3.txt";' ],
  resourceBuffer: <Buffer 48 65 6c 6c 6f 20 77 6f 72 6c 64 0a>,
  cacheable: true,
  fileDependencies: [ './demo.txt' ],
  contextDependencies: [] }

可以看出结果与 loader 应返回的内容一致。 你可以尝试将更多选项传递给 loader 或使用查询参数来查看不同组合会发生什么。

连接 webpack 与 自定义 loader

为了进行一步地使用 loader,我们需要将它与 webpack 联系起来。在这里,我们采用内联的形式引入自定义 loader

// webpack.config.js 中引入
resolveLoader: {
    alias: {
        "demo-loader": path.resolve(
            __dirname,
            "loaders/demo-loader.js"
        ),
    },
},
// 在文件中指定 loader,引入
import "!demo-loader?name=foo!./main.css"

当然你还可以通过规则处理 loader。一旦它足够稳定,就建立一个基于 webpack-defaults 的项目,将逻辑推送到 npm,然后开始将 loader 作为包使用。

尽管我们使用 loader-runner 来作为开发、测试 loader 的环境。但是它与 webpack 还是有细微的不同的,所以还需要在 webpack 上测试一下。

Pitch Loaders

webpack 分为两个阶段来执行 loader:pitching、evaluating。如果你熟悉 web 的事件系统,它与事件的捕获、冒泡很相似。webpack 允许你在 pitching 阶段进行拦截执行。它的顺序是,从左到右pitch,从右到左执行。

一个 pitch loader 允许你对请求进行修改,甚至终止它。 例如,创建

loaders/pitch-loader.js

const loaderUtils = require("loader-utils");

module.exports = function(input) {
  const { text } = loaderUtils.getOptions(this);

  return input + text;
};
module.exports.pitch = function(remainingReq, precedingReq, input) {
  console.log(`
Remaining request: ${remainingReq}
Preceding request: ${precedingReq}
Input: ${JSON.stringify(input, null, 2)}
  `);

  return "pitched";
};

并将其添加到 run-loader.js 中,

...
loaders: [
    {
        loader: path.resolve (__dirname, './loaders/demo-loader'),
        options: {
            name: 'demo.[ext]',
        },
    },
    path.resolve(__dirname, "./loaders/pitch-loader"),
],
...

执行 node run-loader.js

Remaining request: ./demo.txt
Preceding request: .../webpack-demo/loaders/demo-loader?{"name":"demo.[ext]"}
Input: {}

{ result: [ 'export default __webpack_public_path__ + "demo.txt";' ],
  resourceBuffer: null,
  cacheable: true,
  fileDependencies: [],
  contextDependencies: [] }

你会发现 pitch-loader 完成了信息的插入以及执行的拦截。

总结

webpack loader 实质上就是在描述一种文件格式如何转换为另一种文件格式。你可以通过研究 API 文档或现有的 loader 来弄清楚如何实现特定的功能。

回顾下:

  • loader-runner 是一个非常实用的工具,用来开发、调试 loader;
  • webpack loader 是依据输入来生成输出的;
  • loader 分为同步、异步两种形式,异步的可以通过 this.async 来编写异步的 loader;
  • 可以利用 loader 来为 webpack 动态地生成代码,这种情况下,loader 不必接受输入;
  • 使用 loader-utils 能够编译 loader 的配置,还可以通过 schema-utils 进行验证;
  • 利用 resolveLoader.alias 来完成局部的自定义 loader 引入,防止影响全局;
  • Pitching 阶段允许你对 loader 的输入进行修改或拦截执行顺序。