CC 4.0 协议声明

本节内容派生于以下链接指向的内容 ,并遵守 CC BY 4.0 许可证的规定。

以下内容如果没有特殊声明,可以认为都是基于原内容的修改和删减后的结果。

Externals

外部依赖:该选项提供了「从输出的 bundle 中排除依赖」的方法。相反,所创建的 bundle 依赖于那些存在于用户环境(consumer's environment)中的依赖。此功能通常对库开发人员来说是最有用的,然而也会有各种各样的应用程序用到它。

externals

  • 类型: string | object | function | RegExp | Array<string | object | function | RegExp>

防止将某些 import 的包(package)打包到 bundle 中,而是在运行时(runtime)再去从外部获取这些扩展依赖(external dependencies)。

例如,从 CDN 引入 jQuery,而不是把它打包:

index.html

<script
  src="https://code.jquery.com/jquery-3.1.0.js"
  integrity="sha256-slogkvB1K3VOkzAI8QITxV3VzpOnkeNVsKvtkYLMjfk="
  crossorigin="anonymous"
></script>
rspack.config.js
module.exports = {
  //...
  externals: {
    jquery: 'jQuery',
  },
};

这样就剥离了那些不需要改动的依赖模块,换句话,下面展示的代码还可以正常运行:

import $ from 'jquery';

$('.my-element').animate(/* ... */);

上面 rspack.config.jsexternals 下指定的属性名称 jquery 表示 import $ from 'jquery' 中的模块 jquery 应该从打包产物中排除。为了替换这个模块,jQuery 值将用于检索全局 jQuery 变量,因为默认的外部库类型是 var,请参阅 externalsType

虽然我们在上面展示了一个使用外部全局变量的示例,但实际上可以以以下任何形式使用外部变量:全局变量、CommonJS、AMD、ES2015 模块,在 externalsType 中查看更多信息。

字符串

根据 externalsType,这可能是全局变量的名称(参见 'global''this''var ''window')或模块的名称(参见 amdcommonjsmoduleumd)。

如果你只定义 1 个 external,您也可以使用快捷语法:

module.exports = {
  //...
  externals: 'jquery',
};

equals to

module.exports = {
  //...
  externals: {
    jquery: 'jquery',
  },
};

您可以使用 ${externalsType} ${libraryName} 语法为外部指定外部库类型。它将覆盖 externalsType 选项中指定的默认外部库类型。

例如,如果外部库是一个 CommonJS 模块,你可以指定

module.exports = {
  //...
  externals: {
    jquery: 'commonjs jquery',
  },
};

对象

带有 { root, amd, commonjs, ... } 的对象只允许用于 libraryTarget: 'umd'externalsType: 'umd'。其他库的 target 不允许这样做。

module.exports = {
  //...
  externals: {
    react: 'react',
  },

  // 或者

  externals: {
    lodash: {
      commonjs: 'lodash',
      amd: 'lodash',
      root: '_', // 指向全局变量
    },
  },
};

此语法用于描述外部 library 所有可用的访问方式。这里 lodash 这个外部 library 可以在 AMD 和 CommonJS 模块系统中通过 lodash 访问,但在全局变量形式下用 _ 访问。subtract 可以通过全局 math 对象下的属性 subtract 访问(例如 window['math']['subtract'])。

externalsType

  • 类型: string
  • 默认值: var

指定 externals 的默认类型。当 external 被设置为 amdumdsystem 以及 jsonp 时,output.libraryTarget 的值也应相同。例如,你只能在 amd 库中使用 amd 的 externals。

支持的类型如下:

externalsType.commonjs

将外部的默认类型指定为“commonjs”。Webpack 将为模块中使用的外部生成类似 const X = require('...') 的代码。

import fs from 'fs-extra';
rspack.config.js
module.exports = {
  // ...
  externalsType: 'commonjs',
  externals: {
    'fs-extra': 'fs-extra',
  },
};

将会转换为类似下面的代码:

const fs = require('fs-extra');

请注意,输出产物中会有一个 require()

externalsType.global

将外部的默认类型指定为 'global'。Webpack 会将 external 作为全局变量读取到 globalObject

import jq from 'jquery';
jq('.my-element').animate(/* ... */);
rspack.config.js
module.exports = {
  // ...
  externalsType: 'global',
  externals: {
    jquery: '$',
  },
  output: {
    globalObject: 'global',
  },
};

将会转换为类似下面的代码:

const jq = global['$'];
jq('.my-element').animate(/* ... */);

externalsType.node-commonjs

将 externals 类型设置为 'node-commonjs',webpack 将从 module 中导入 createRequire 来构造一个 require 函数,用于加载模块中使用的外部对象。

import jq from 'jquery';
jq('.my-element').animate(/* ... */);
rspack.config.js
module.export = {
  externalsType: 'node-commonjs',
  externals: {
    jquery: 'jquery',
  },
};

将会转换为类似下面的代码:

import { createRequire } from 'module';

const jq = createRequire(import.meta.url)('jquery');
jq('.my-element').animate(/* ... */);

请注意,输出包中会有一个 import 语句。

externalsType.self

将外部的默认类型指定为 'self'。 Webpack 会将 external 作为 self 对象上的全局变量读取。

import jq from 'jquery';
jq('.my-element').animate(/* ... */);
rspack.config.js
module.exports = {
  // ...
  externalsType: 'self',
  externals: {
    jquery: '$',
  },
};

将会转换为类似下面的代码:

const jq = self['$'];
jq('.my-element').animate(/* ... */);

externalsType.this

将 external 的默认类型指定为 'this'。Webpack 会将 external 作为 this 对象上的全局变量读取。

示例

import jq from 'jquery';
jq('.my-element').animate(/* ... */);
rspack.config.js
module.exports = {
  // ...
  externalsType: 'this',
  externals: {
    jquery: '$',
  },
};

将会转换为类似下面的代码:

const jq = this['$'];
jq('.my-element').animate(/* ... */);

externalsType.var

将 external 的默认类型指定为 'var'。Webpack 会将 external 作为全局变量读取。

示例

import jq from 'jquery';
jq('.my-element').animate(/* ... */);
rspack.config.js
module.exports = {
  // ...
  externalsType: 'var',
  externals: {
    jquery: '$',
  },
};

将会转换为类似下面的代码:

const jq = $;
jq('.my-element').animate(/* ... */);

externalsType.window

将 external 的默认类型指定为 'window'。Webpack 会将 external 作为 window 对象上的全局变量读取。

示例

import jq from 'jquery';
jq('.my-element').animate(/* ... */);
rspack.config.js
module.exports = {
  // ...
  externalsType: 'window',
  externals: {
    jquery: '$',
  },
};

将会转换为类似下面的代码:

const jq = window['$'];
jq('.my-element').animate(/* ... */);

externalsPresets

为特定的目标环境启用外部模块的预设值。

externalsPresets.node

将 node.js 的内置模块(如 fspathvm)视为外部模块,并在使用时通过 require() 加载它们。

externalsPresets.web

将对 http(s)://...std:... 引入的模块视为外部模块,并在使用时通过 import (externalType: "module") 来加载它们(请注意,这会改变执行顺序,因为外部模块的代码会在 Chunk 中的任何其他模块的代码之前执行)。

externalsPresets.webAsync

将对 http(s)://...std:... 引入的模块视为外部模块,并在使用时通过 import() (externalType: "import") 来加载它们(请注意,此 external 类型为 async 模块,它对执行会产生各种副作用)。

externalsPresets.electron

将 Electron 主进程和预加载脚本中常见的 Electron 内置模块如 electronipcshell 视为外部模块,并在使用时通过 require() 加载它们。

externalsPresets.electronMain

将 Electron 主进程中常见的 Electron 内置模块如 appipc-mainshell 视为外部模块,并在使用时通过 require() 加载它们。

externalsPresets.electronRenderer

将 Electron 渲染进程中常见的 Electron 内置模块如 web-frameipc-renderershell 视为外部模块,并在使用时通过 require() 加载它们。

externalsPresets.electronPreload

将 Electron 预加载脚本中常见的 Electron 内置模块如 web-frameipc-renderershell 视为外部模块,并在使用时通过 require() 加载它们。