本节内容派生于以下链接指向的内容 ,并遵守 CC BY 4.0 许可证的规定。
以下内容如果没有特殊声明,可以认为都是基于原内容的修改和删减后的结果。
外部依赖:该选项提供了「从输出的 bundle 中排除依赖」的方法。相反,所创建的 bundle 依赖于那些存在于用户环境(consumer's environment)中的依赖。此功能通常对库开发人员来说是最有用的,然而也会有各种各样的应用程序用到它。
string | object | function | RegExp | Array<string | object | function | RegExp>
防止将某些 import
的包(package)打包到 bundle 中,而是在运行时(runtime)再去从外部获取这些扩展依赖(external dependencies)。
例如,从 CDN 引入 jQuery,而不是把它打包:
index.html
这样就剥离了那些不需要改动的依赖模块,换句话,下面展示的代码还可以正常运行:
上面 rspack.config.js
中 externals
下指定的属性名称 jquery
表示 import $ from 'jquery'
中的模块 jquery
应该从打包产物中排除。为了替换这个模块,jQuery
值将用于检索全局 jQuery
变量,因为默认的外部库类型是 var
,请参阅 externalsType。
虽然我们在上面展示了一个使用外部全局变量的示例,但实际上可以以以下任何形式使用外部变量:全局变量、CommonJS、AMD、ES2015 模块,在 externalsType 中查看更多信息。
根据 externalsType,这可能是全局变量的名称(参见 'global'
、'this'
、'var '
、'window'
)或模块的名称(参见 amd
、commonjs
、module
、umd
)。
如果你只定义一个 external,也可以使用快捷语法:
等价于
你可以使用 ${externalsType} ${libraryName}
语法来指定外部库类型。它将覆盖 externalsType 选项中指定的默认外部库类型。
例如,如果外部库是一个 CommonJS 模块,你可以指定
subtract: ['./math', 'subtract']
允许你选择一个模块的一部分,其中 ./math
是模块名,你的打包只需要包含 subtract
变量下的子集。
当 externalsType
为 commonjs
时,这个例子会编译为 require('./math').subtract
;当 externalsType
为 window
时,这个例子会编译为 window["./math"]["subtract"]
。
与字符串语法类似,你可以在数组的第一个元素中使用 ${externalsType} ${libraryName}
语法指定外部库类型,例如:
带有 { root, amd, commonjs, ... }
的对象只允许用于 libraryTarget: 'umd'
和 externalsType: 'umd'
。其他库的 target 不允许这样做。
此语法用于描述外部 library 所有可用的访问方式。这里 lodash
这个外部库可以在 AMD 和 CommonJS 模块系统中通过 lodash
访问,但在全局变量形式下用 _
访问。subtract
可以通过全局 math
对象下的属性 subtract
访问(例如 window['math']['subtract']
)。
类型:
function ({ context, request, contextInfo, getResolve }, callback)
function ({ context, request, contextInfo, getResolve }) => promise
如果你想要自定义外部化的行为,可以使用函数。例如使用 webpack-node-externals 排除所有来自 node_modules
目录的模块,并提供了选项来允许列出白名单中的包。
函数接收两个入参:
ctx
(object
): 包含文件的详细信息的对象。
ctx.context
(string
): 包含 import 的文件的目录。ctx.request
(string
): 被请求的 import 路径。ctx.contextInfo
(object
): 包含有关发起者的信息(例如 layer 和编译器)。ctx.getResolve
: 获取一个带有当前解析器选项的解析函数。callback
(function (err, result, type)
): 用来指示模块如何被外部化的回调函数。回调函数接收三个参数:
err
(Error
): 用于标识外部化导入时是否出现错误。如果有错误,这应该是唯一使用的参数。result
(string | string[] | object
): 使用其他外部格式描述外部模块(字符串,字符串数组或对象 )。type
(string
): 指示 externalsType 的可选参数(如果还没有在 result
参数中指出的话)。例如,要外部化所有导入路径与正则表达式匹配的导入,可以这样做:
其他使用不同模块格式的例子:
符合给定正则表达式的每个依赖项都将从打包产物中排除。
在这种情况下,任何名为 jQuery
的依赖项,无论是否大写,或者 $
,都将被外部化。
有时你可能希望使用上述语法的组合。这可以通过以下方式完成:
如果没有指定类型,将使用默认类型,例如 externals: { react: 'react' }
而不是 externals: { react: 'commonjs-module react' }
。
string
'var'
指定 externals 的默认类型。当 external 被设置为 amd
,umd
,system
以及 jsonp
时,output.libraryTarget
的值也应相同。例如,你只能在 amd
库中使用 amd
的 externals。
支持的类型如下:
'amd'
'amd-require'
'assign'
- 同 'var'
'commonjs'
'commonjs-module'
'global'
'import'
- 使用 import()
加载一个原生的 ECMAScript 模块(异步模块)'jsonp'
'module'
'node-commonjs'
'promise'
'self'
'system'
'script'
'this'
'umd'
'umd2'
'var'
'window'
将 externals 的默认类型指定为 'commonjs'
。Rspack 将为模块中使用的外部生成类似 const X = require('...')
的代码。
示例
将会转换为类似下面的代码:
请注意,输出产物中会有一个 require()
。
将 externals 的默认类型指定为 'global'
。Rspack 会将 external 视为 globalObject
上的一个全局变量读取。
示例
将会转换为类似下面的代码:
将 externals 的默认类型指定为 'module'
。Rspack 将为模块中使用的 externals 生成类似 import * as X from '...'
的代码。
确保开启了 experimental.outputModule
,否则 Rspack 会抛出错误。
示例
将生成类似于以下内容的东西
请注意,在输出包中将有一个 import
语句。
将 externals 类型设置为 'node-commonjs'
,Rspack 将从 module
中导入 createRequire
来构造一个 require 函数,用于加载模块中使用的外部对象。
示例
将会转换为类似下面的代码:
请注意,输出包中会有一个 import
语句。
将 externals 的默认类型指定为 'promise'
,Rspack 会将 external 视为全局变量(类似于 'var'
)并 await 它。
例子
将会转换为类似下面的代码:
将外部的默认类型指定为 'self'
。 Rspack 会将 external 作为 self
对象上的全局变量读取。
将会转换为类似下面的代码:
将 external 的默认类型指定为 'script'
。Rspack 会使用 HTML <script>
标签加载外部资源,暴露预定义的全局变量。脚本加载完成后,<script>
标签将被移除。
语法
如果不打算指定任何属性也可以使用快捷语法:
请注意,output.publicPath 不会被添加到提供的 URL 中。
示例
让我们从 CDN 加载一个 lodash
:
然后在代码中使用:
下面是我们如何为上述示例指定属性的方法:
局部变量 head
和全局 window._
在导入 lodash
时都将被暴露出来。
当使用 HTML <script>
标签加载代码时,Rspack 运行时会尝试查找与 src
属性匹配或具有特定 data-webpack
属性的现有 <script>
标签。对于 chunk 加载,data-webpack
属性的值将是 '[output.uniqueName]:chunk-[chunkId]'
,而外部脚本的值将是 '[output.uniqueName]:[global]'
。
将 external 的默认类型指定为 'this'
。Rspack 会将 external 作为 this
对象上的全局变量读取。
示例
将会转换为类似下面的代码:
将 external 的默认类型指定为 'var'
。Rspack 会将 external 作为全局变量读取。
示例
将会转换为类似下面的代码:
将 external 的默认类型指定为 'window'
。Rspack 会将 external 作为 window
对象上的全局变量读取。
示例
将会转换为类似下面的代码:
object
为特定的目标环境启用外部模块的预设值。
类型:boolean
将 Electron 主进程和预加载脚本中常见的 Electron 内置模块如 electron
、ipc
或 shell
视为外部模块,并在使用时通过 require()
加载它们。
类型:boolean
将 Electron 主进程中常见的 Electron 内置模块如 app
、ipc-main
或 shell
视为外部模块,并在使用时通过 require()
加载它们。
类型:boolean
将 Electron 预加载脚本中常见的 Electron 内置模块如 web-frame
、ipc-renderer
或 shell
视为外部模块,并在使用时通过 require()
加载它们。
类型:boolean
将 Electron 渲染进程中常见的 Electron 内置模块如 web-frame
、ipc-renderer
或 shell
视为外部模块,并在使用时通过 require()
加载它们。
类型:boolean
将 node.js 的内置模块(如 fs
、path
或 vm
)视为外部模块,并在使用时通过 require()
加载它们。
类型:boolean
将 NW.js 旧版 nw.gui
模块视为外部模块,并在使用时通过 require()
加载它。
类型:boolean
将对 http(s)://...
和 std:...
引入的模块视为外部模块,并在使用时通过 import
(externalType: "module"
) 来加载它们 (请注意,这会改变执行顺序,因为外部模块的代码会在 chunk 中的任何其他模块的代码之前执行)。
类型:boolean
将对 http(s)://...
和 std:...
引入的模块视为外部模块,并在使用时通过 async import()
来加载它们 (注意,外部模块的类型是 async
模块,对执行有各种影响)。
请注意,如果你打算输出 ES 模块并使用这些 node.js 相关的预设值,Rspack 将会将默认的 externalsType
设置为 node-commonjs
,这将使用 createRequire
来构造一个 require 函数,而不是使用 require()
。
示例
使用 node
预设将不会打包内置模块,并将它们视为外部模块,当使用时通过 require()
加载它们。