babel-loader

此 package 允许你使用 Babelwebpack 转译 JavaScript 文件。

注意:请在 Babel Issues tracker 上报告输出时遇到的问题。

中文文档

Babel 中文文档

安装

webpack 4.x | babel-loader 8.x | babel 7.x

  1. npm install -D babel-loader @babel/core @babel/preset-env webpack

用法

webpack 文档:loaders

在 webpack 配置对象中,需要将 babel-loader 添加到 module 列表中,就像下面这样:

  1. module: {
  2. rules: [
  3. {
  4. test: /\.m?js$/,
  5. exclude: /(node_modules|bower_components)/,
  6. use: {
  7. loader: 'babel-loader',
  8. options: {
  9. presets: ['@babel/preset-env']
  10. }
  11. }
  12. }
  13. ]
  14. }

选项

查看 babel 选项

你可以使用 options 属性,来向 loader 传递 options 选项:

  1. module: {
  2. rules: [
  3. {
  4. test: /\.m?js$/,
  5. exclude: /(node_modules|bower_components)/,
  6. use: {
  7. loader: 'babel-loader',
  8. options: {
  9. presets: ['@babel/preset-env'],
  10. plugins: ['@babel/plugin-proposal-object-rest-spread']
  11. }
  12. }
  13. }
  14. ]
  15. }

此 loader 也支持下面这些 loader 特有的选项:

  • cacheDirectory:默认值为 false。当有设置时,指定的目录将用来缓存 loader 的执行结果。之后的 webpack 构建,将会尝试读取缓存,来避免在每次执行时,可能产生的、高性能消耗的 Babel 重新编译过程(recompilation process)。如果设置了一个空值 (loader: 'babel-loader?cacheDirectory') 或者 true (loader: 'babel-loader?cacheDirectory=true'),loader 将使用默认的缓存目录 node_modules/.cache/babel-loader,如果在任何根目录下都没有找到 node_modules 目录,将会降级回退到操作系统默认的临时文件目录。

  • cacheIdentifier:默认是由 @babel/core 版本号,babel-loader 版本号,.babelrc 文件内容(存在的情况下),环境变量 BABEL_ENV 的值(没有时降级到 NODE_ENV)组成的一个字符串。可以设置为一个自定义的值,在 identifier 改变后,来强制缓存失效。

  • cacheCompression:默认值为 true。当设置此值时,会使用 Gzip 压缩每个 Babel transform 输出。如果你想要退出缓存压缩,将它设置为 false — 如果你的项目中有数千个文件需要压缩转译,那么设置此选项可能会从中收益。

  • customize: 默认值为 null。导出 custom 回调函数的模块路径,例如传入 .custom() 的 callback 函数。由于你必须创建一个新文件才能使用它,建议改为使用 .custom 来创建一个包装 loader。只有在你_必须_继续直接使用 babel-loader 但又想自定义的情况下,才使用这项配置。

疑难解答

babel-loader 很慢!

确保转译尽可能少的文件。你可能使用 /\.m?js$/ 来匹配,这样也许会去转译 node_modules 目录或者其他不需要的源代码。

要排除 node_modules,参考文档中的 loaders 配置的 exclude 选项。

你也可以通过使用 cacheDirectory 选项,将 babel-loader 提速至少两倍。这会将转译的结果缓存到文件系统中。

Babel 在每个文件都插入了辅助代码,使代码体积过大!

Babel 对一些公共方法使用了非常小的辅助代码,比如 _extend。默认情况下会被添加到每一个需要它的文件中

你可以引入 Babel runtime 作为一个独立模块,来避免重复引入。

下面的配置禁用了 Babel 自动对每个文件的 runtime 注入,而是引入 @babel/plugin-transform-runtime 并且使所有辅助代码从这里引用。

更多信息请查看 文档

注意:你必须执行 npm install -D @babel/plugin-transform-runtime 来把它包含到你的项目中,然后使用 npm install @babel/runtime@babel/runtime 安装为一个依赖。

  1. rules: [
  2. // 'transform-runtime' 插件告诉 Babel
  3. // 要引用 runtime 来代替注入。
  4. {
  5. test: /\.m?js$/,
  6. exclude: /(node_modules|bower_components)/,
  7. use: {
  8. loader: 'babel-loader',
  9. options: {
  10. presets: ['@babel/preset-env'],
  11. plugins: ['@babel/plugin-transform-runtime']
  12. }
  13. }
  14. }
  15. ]

注意:transform-runtime 和自定义 polyfills (例如 Promise library)

由于 @babel/plugin-transform-runtime 包含了一个 polyfill,含有自定义的 regenerator-runtimecore-js, 下面使用 webpack.ProvidePlugin 来配置 shimming 的常用方法将没有作用:

  1. // ...
  2. new webpack.ProvidePlugin({
  3. 'Promise': 'bluebird'
  4. }),
  5. // ...

下面这样的写法也没有作用:

  1. require('@babel/runtime/core-js/promise').default = require('bluebird');
  2. var promise = new Promise;

它其实会生成下面这样 (使用了 runtime 后):

  1. 'use strict';
  2. var _Promise = require('@babel/runtime/core-js/promise')['default'];
  3. require('@babel/runtime/core-js/promise')['default'] = require('bluebird');
  4. var promise = new _Promise();

前面的 Promise library 在被覆盖前已经被引用和使用了。

一种可行的办法是,在你的应用程序中加入一个“引导(bootstrap)”步骤,在应用程序开始前先覆盖默认的全局变量。

  1. // bootstrap.js
  2. require('@babel/runtime/core-js/promise').default = require('bluebird');
  3. // ...
  4. require('./app');

babel 的 Node.js API 已经被移到 babel-core 中。(原文:The Node.js API for babel has been moved to babel-core.)

如果你收到这个信息,这说明你有一个已经安装的 babel npm package,并且在 webpack 配置中使用 loader 简写方式(在 webpack 2.x 版本中将不再支持这种方式)。

  1. {
  2. test: /\.m?js$/,
  3. loader: 'babel',
  4. }

webpack 将尝试读取 babel package 而不是 babel-loader

想要修复这个问题,你需要卸载 babel npm package,因为它在 Babel v6 中已经被废除。(安装 @babel/cli 或者 @babel/core 来替代它) 在另一种场景中,如果你的依赖于 babel 而无法删除它,可以在 webpack 配置中使用完整的 loader 名称来解决:

  1. {
  2. test: /\.m?js$/,
  3. loader: 'babel-loader',
  4. }

自定义 loader

babel-loader 提供了一个 loader-builder 工具函数, 允许用户为 Babel 处理过的每个文件添加自定义处理选项。

.custom 接收一个 callback 函数, 它将被调用,并传入 loader 中的 babel 实例, 因此,此工具函数才能够完全确保它使用与 loader 的 @babel/core 相同的实例。

如果你想自定义,但实际上某个文件又不想调用 .custom, 可以向 customize 选项传入一个字符串, 此字符串指向一个导出 custom 回调函数的文件。

示例

  1. // 从 "./my-custom-loader.js" 中导出,或者任何你想要的文件中导出。
  2. module.exports = require("babel-loader").custom(babel => {
  3. function myPlugin() {
  4. return {
  5. visitor: {},
  6. };
  7. }
  8. return {
  9. // 传给 loader 的选项。
  10. customOptions({ opt1, opt2, ...loader }) {
  11. return {
  12. // 获取 loader 可能会有的自定义选项
  13. custom: { opt1, opt2 },
  14. // 传入"移除了两个自定义选项"后的选项
  15. loader,
  16. };
  17. },
  18. // 提供 Babel 的 'PartialConfig' 对象
  19. config(cfg) {
  20. if (cfg.hasFilesystemConfig()) {
  21. // 使用正常的配置
  22. return cfg.options;
  23. }
  24. return {
  25. ...cfg.options,
  26. plugins: [
  27. ...(cfg.options.plugins || []),
  28. // 在选项中包含自定义 plugin
  29. myPlugin,
  30. ],
  31. };
  32. },
  33. result(result) {
  34. return {
  35. ...result,
  36. code: result.code + "\n// Generated by some custom loader",
  37. };
  38. },
  39. };
  40. });
  1. // 然后,在你的 webpack config 文件中
  2. module.exports = {
  3. // ..
  4. module: {
  5. rules: [{
  6. // ...
  7. loader: path.join(__dirname, 'my-custom-loader.js'),
  8. // ...
  9. }]
  10. }
  11. };

customOptions(options: Object): { custom: Object, loader: Object }

指定的 loader 的选项, 从 babel-loader 选项中分离出自定义选项。

config(cfg: PartialConfig): Object

指定的 Babel 的 PartialConfig 对象, 返回应该被传递给 babel.transformoption 对象。

result(result: Result): Result

指定的 Babel 结果对象,允许 loaders 对它进行额外的调整。

License

MIT