WebPack Output,WebPack输出
WebPack Output
output 位于对象最顶级键(key),了一组选项,指示 webpack 如何去、以及在哪里你的「bundle、asset 和其他你所打包或使用 webpack 载入的任何」。
output.auxiliaryComment
string object
在和 output.library 和 output.libraryTarget 一起使用时,此选项允许向导出容器(export wrapper)中插入注释。要为 libraryTarget 每种类型都插入相同的注释,将 auxiliaryComment 设置为字符串:
output: { library: "someLibName", libraryTarget: "umd", filename: "someLibName.js", auxiliaryComment: "Test Comment" }
将会如下:
(function webpackUniversalModuleDen(root, factory) { // Test Comment if(typeof exports === 'object' && typeof module === 'object') module.exports = factory(require("lodash")); // Test Comment else if(typeof define === 'function' && define.amd) define(["lodash"], factory); // Test Comment else if(typeof exports === 'object') exports["someLibName"] = factory(require("lodash")); // Test Comment else root["someLibName"] = factory(root["_"]);})(this, function(__WEBPACK_EXTERNAL_MODULE_1__) { // ...});
对于 libraryTarget 每种类型的注释进行更细粒度地控制,请传入对象:
auxiliaryComment: { root: "Root Comment", commonjs: "CommonJS Comment", commonjs2: "CommonJS2 Comment", amd: "AMD Comment" }
output.chunkFilename
string function
此选项决定了非入口(non-entry) chunk 的。有关可取的值的详细信息,请查看 output.filename 选项。
注意,这些名需要在 runtime 根据 chunk 发送的请求去。因此,需要在 webpack runtime bundle 值时,将 chunk id 的值对应映射到占位符(如 [name] 和 [chunkhash])。这会大小,并且在任何 chunk 的占位符值后,都会使 bundle 失效。
认使用 [id].js 或从 output.filename 中推断出的值([name] 会被预先替换为 [id] 或 [id].)。
output.chunkLoadTimeout
integer
chunk 请求到期之前的毫秒数,认为 120 000。从 webpack 2.6.0 开始此选项。
output.crossOriginLoading
boolean string
只用于 target 是 web,使用了通过 script 的 JSONP 来按需加载 chunk。
启用 加载 chunk。以下是可接收的值……
crossOriginLoading: false - 禁用跨域加载(认)
crossOriginLoading: "anonymous" - 不带凭据(credential)启用跨域加载
crossOriginLoading: "use-credentials" - 带凭据(credential)启用跨域加载 with credentials
output.jsonpScriptType
string
允许 script 的类型,webpack 会将 script 注入到 DOM 中以下载异步 chunk。可以使用以下选项:
"text/javascript"(认)
"module":与 ES6 就绪一起使用。
output.devtoolFallbackModuleFilenameTemplate
string | function(info)
当上面的模板字符串或产生重复时使用的备用。
查看 output.devtoolModuleFilenameTemplate。
output.devtoolLineToLine
boolean | object
避免使用此选项,因为它们已废弃,并将很快。 it is deprecated and will soon be removed.
对所有或某些模块启用「行到行映射(line to line mapping)」。这将基本的源映射(source map),即资源(generated source)的每一行,映射到原始资源(original source)的同一行。这是优化点,并且应该只需要输入行(input line)和行(generated line)相匹配时才使用。
传入 boolean 值,对所有模块启用或禁用此(认 false)。对象可有 test, include, exclude 三种。例如,对某个特定目录中所有 javascript 启用此:
devtoolLineToLine: { test: /\.js$/, include: 'src/utilities' }
output.devtoolModuleFilenameTemplate
string | function(info)
此选项仅在 「devtool 使用了需要模块的选项」时使用。
每个 source map 的 sources 数组中使用的。可以通过传递模板字符串(template string)或者来完成。例如,当使用 devtool: 'eval',认值是:
devtoolModuleFilenameTemplate: "webpack://[namespace]/[resource-path]?[loaders]"
模板字符串(template string)中做以下替换(通过 webpack 内部的 ):
当使用,同样的选项要通过 info 参数并使用驼峰式(camel-cased):
devtoolModuleFilenameTemplate: info => { return `webpack:///${info.resourcePath}?${info.loaders}` }
如果多个模块产生相同的,使用 output.devtoolFallbackModuleFilenameTemplate 来代替这些模块。
output.devtoolNamespace
string
此选项确定 output.devtoolModuleFilenameTemplate 使用的模块空间。未指定时的认值为:output.library。在加载多个通过 webpack 构建的 library 时,用于防止 sourcemap 中源路径冲突。
例如,如果你有两个 library,分别使用命名空间 library1 和 library2,并且都有 ./src/index.js(可能具有不同),它们会将这些暴露为 webpack://library1/./src/index.js和 webpack://library2/./src/index.js。
output.filename
string function
此选项决定了每个 bundle 的。这些 bundle 将写入到 output.path 选项指定的目录下。
对于单个入口起点,filename 会是静态。
filename: "bundle.js"
然而,当通过多个入口起点(entry point)、拆分(code splitting)或各种(plugin)创建多个 bundle,应该使用以下一种替换方式,来赋予每个 bundle 唯一的……
使用入口:
filename: "[name].bundle.js"
使用内部 chunk id
filename: "[id].bundle.js"
使用每次构建过程中,唯一的 hash
filename: "[name].[hash].bundle.js"
使用基于每个 chunk 的 hash:
filename: "[chunkhash].bundle.js"
请确保已阅读过指南 - 缓存的详细信息。这里涉及更多步骤,不仅仅是设置此选项。
注意此选项被称为名,但是你还是可以使用像 "js/[name]/bundle.js" 这样的夹结构。
注意,此选项不会影响那些「按需加载 chunk」的。对于这些,请使用 output.chunkFilename选项来控制。通过 loader 创建的也不受影响。种情况下,你必须尝试 loader 特定的可用选项。
可以使用以下替换模板字符串(通过 webpack 内部的[TemplatedPathPlugin]):
[hash] 和 [chunkhash] 的长度可以使用 [hash:16](认为20)来指定。或者,通过指定output.hashDigestLength 在全局配置长度。
如果将这个选项设为,将返回包含上面表格中替换信息的对象。
在使用 ExtractTextWebpackPlugin 时,可以用 [contenthash] 来的 hash(既不是 [hash] 也不是 [chunkhash])。
output.hashDigest
在 hash 时使用的编码方式,认为 'hex'。 Node.js 的所有编码。
output.hashDigestLength
散列的前缀长度,认为 20。
output.hashFunction
string|function
散列算法,认为 'md5'。 Node.JS 的所有。从 4.0.0-alpha2 开始,hashFunction 现在可以是返回 hash 的构造。出于原因,你可以提供不加密的哈希(non-crypto hash function)。
hashFunction: require('metrohash').MetroHash64
确保 hash 有可访问的 update and digest 。
output.hashSalt
可选的加盐值,通过 Node.JS 来更新哈希。
output.hotUpdateChunkFilename
string function
热更新 chunk 的名。可选的值的详细信息,请查看 output.filename 选项。
占位符只能是 [id] 和 [hash],认值是:
hotUpdateChunkFilename: "[id].[hash].hot-update.js"
这里没有必要它。
output.hotUpdateFunction
function
只在 target 是 web 时使用,用于加载热更新(hot update)的 JSONP 。
JSONP 用于异步加载(async load)热更新(hot-update) chunk。
详细请查看 output.jsonpFunction。
output.hotUpdateMainFilename
string function
热更新的主名(main filename)。可选的值的详细信息,请查看 output.filename 选项
占位符只能是 [hash],认值是:
hotUpdateMainFilename: "[hash].hot-update.json"
这里没有必要它。
output.jsonpFunction
string
只在 target 是 web 时使用,用于按需加载(load on-demand) chunk 的 JSONP 。
JSONP 用于异步加载(async load) chunk,或者拼接多个初始 chunk(CommonsChunkPlugin, AggressiveSplittingPlugin)。
如果在同一网页中使用了多个(来自不同编译过程(compilation)的)webpack runtime,则需要此选项。
如果使用了 output.library 选项,library 时追加的。
output.library
string
string 或 object(从 webpack 3.1.0 开始;用于 libraryTarget: "umd")
output.library 的值的作用,取决于output.libraryTarget 选项的值;完整的详细信息请查阅该章节。注意,output.libraryTarget 的认选项是 var,所以如果使用以下配置选项:
output: { library: "MyLibrary" }
如果的,是在 HTML 中作为 script 引入,则变量 MyLibrary 将与入口的返回值绑定。
注意,如果将数组作为 entry,那么只会暴露数组中的最后模块。如果将对象作为 entry,还可以使用数组语法暴露(具体查看 for details))。
有关 output.library 以及 output.libraryTarget 详细信息,请查看创建 library 指南。
output.libraryExport
string or string[] (since webpack 3.0.0)
Default: _entry_return_
Conure which module or modules will be exposed via the libraryTarget. The default _entry_return_ value is the namespace or default module returned by your entry file. The examples below demonstrate the effect of this con when using libraryTarget: "var", but any target may be used.
The following conurations are supported:
libraryExport: "default" - The default export of your entry point will be assigned to the library target:
// if your entry has a default export of `MyDefaultModule` var MyDefaultModule = _entry_return_.default;
libraryExport: "MyModule" - The specified module will be assigned to the library target:
var MyModule = _entry_return_.MyModule;
libraryExport: ["MyModule", "MySubModule"] - The array is interpreted as a path to a module to be assigned to the library target:
var MySubModule = _entry_return_.MyModule.MySubModule;
With the libraryExport conurations specified above, the resulting libraries be utilized as such:
MyDefaultModule.doSomething(); MyModule.doSomething(); MySubModule.doSomething();
output.libraryTarget
string
认值: "var"
配置如何暴露 library。可以使用下面的选项中的任意。注意,此选项与分配给 output.library 的值一同使用。对于下面的所有示例,都假定将 output.library 的值配置为 MyLibrary。
注意,下面的示例中的 _entry_return_ 是入口起点返回的值。在 bundle 本身中,它是从入口起点、由 webpack 的的结果。
暴露为变量
这些选项将入口起点的返回值(例如,入口起点的任何导出值),在 bundle 包所引入的位置,赋值给 output.library 提供的变量名。
libraryTarget: "var" - (认值)当 library 加载完成,入口起点的返回值将分配给变量:
var MyLibrary = _entry_return_; // 在单独的 script…… MyLibrary.doSomething();
当使用此选项时,将 output.library 设置为空,会因为没有变量导致无法赋值。
libraryTarget: "assign" - 这将产生隐含的,可能会潜在地重新分配到全局中已存在的值(谨慎使用)。.
MyLibrary = _entry_return_;
注意,如果 MyLibrary 在作用域中未在前面进行定义,则你的 library 将被设置在全局作用域内。
当使用此选项时,将 output.library 设置为空,将产生破损的 bundle。
通过在对象上赋值暴露
这些选项将入口起点的返回值(例如,入口起点的任何导出值)赋值给特定对象的(此由 output.library 定义)下。
如果 output.library 未赋值为非空字符串,则认行为是,将入口起点返回的所有都赋值给对象(此对象由 output.libraryTarget 特定),通过如下片段:
(function(e, a) { for(var i in a) e[i] = a[i]; }(${output.libraryTarget}, _entry_return_)
注意,不设置 output.library 将导致由入口起点返回的所有,都会被赋值给给定的对象;这里并不会检查现有的名是否存在。
libraryTarget: "this" - 入口起点的返回值将分配给 this 的(此由 output.library 定义)下,this 的含义取决于你:
this["MyLibrary"] = _entry_return_; // 在单独的 script…… this.MyLibrary.doSomething(); MyLibrary.doSomething(); // 如果this是window
libraryTarget: "window" - 入口起点的返回值将使用 output.library 中定义的值,分配给 window 对象的这个下。
window["MyLibrary"] = _entry_return_; window.MyLibrary.doSomething();
libraryTarget: "global" - 入口起点的返回值将使用 output.library 中定义的值,分配给 global 对象的这个下。
global["MyLibrary"] = _entry_return_; global.MyLibrary.doSomething();
libraryTarget: "commonjs" - 入口起点的返回值将使用 output.library 中定义的值,分配给 exports 对象。这个也意味着,模块用于 CommonJS 环境:
exports["MyLibrary"] = _entry_return_; require("MyLibrary").doSomething();
模块定义系统
这些选项将导致 bundle 带有更完整的模块头部,以确保与各种模块系统的兼容性。根据 output.libraryTarget 选项不同,output.library 选项将具有不同的含义。
libraryTarget: "commonjs2" - 入口起点的返回值将分配给 module.exports 对象。这个也意味着模块用于 CommonJS 环境:
module.exports = _entry_return_; require("MyLibrary").doSomething();
注意,output.library 会被省略,因此对于此特定的 output.libraryTarget,无需再设置 output.library 。
想要弄清楚 CommonJS 和 CommonJS2 之区别?虽然它们很相似,但二者之间存在一些微妙的差异,这通常与 webpack 上下文没有关联。(更多详细信息,请。)
libraryTarget: "amd" - 将你的 library 暴露为 AMD 模块。
AMD 模块要求入口 chunk(例如使用 <script> 加载的第脚本)通过特定的定义,例如 define和 require,它们通常由 RequireJS 或任何兼容的模块加载器提供(例如 almond)。否则,直接加载的 AMD bundle 将导致报错,如 define is not defined。
所以,使用以下配置……
output: { library: "MyLibrary", libraryTarget: "amd" }
的 output 将会使用 "MyLibrary" 作为模块名定义,即
define("MyLibrary", [], function() { return _entry_return_; // 此模块返回值,是入口 chunk 返回的值 });
可以在 script 中,将 bundle 作为模块整体引入,并且可以像这样 bundle:
require(['MyLibrary'], function(MyLibrary) { // 使用 library 做一些事…… });
如果 output.library 未定义,将会以下。
define([], function() { return _entry_return_; // 此模块返回值,是入口 chunk 返回的值 });
如果直接加载 <script> ,此 bundle 无法按预期运行,或者根本无法正常运行(在 almond loader 中)。只能通过的实际路径,在 RequireJS 兼容的异步模块加载器中运行,因此种情况下,如果这些设置直接暴露在服务器上,那么 output.path 和 output.filename 对于这个特定的设置可能变得很重要。
libraryTarget: "umd" - 将你的 library 暴露为所有的模块定义下都可运行的方式。它将在 CommonJS, AMD 环境下运行,或将模块导出到 global 下的变量。了解更多请查看 。
个例子中,你需要 library 来命名你的模块:
output: { library: "MyLibrary", libraryTarget: "umd" }
最终如下:
(function webpackUniversalModuleDen(root, factory) { if(typeof exports === 'object' && typeof module === 'object') module.exports = factory(); else if(typeof define === 'function' && define.amd) define([], factory); else if(typeof exports === 'object') exports["MyLibrary"] = factory(); else root["MyLibrary"] = factory(); })(typeof self !== 'undefined' ? self : this, function() { return _entry_return_; // 此模块返回值,是入口 chunk 返回的值 });
注意,省略 library 会导致将入口起点返回的所有,直接赋值给 root 对象,就像对象分配章节。例如:
output: { libraryTarget: "umd" }
结果如下:
(function webpackUniversalModuleDen(root, factory) { if(typeof exports === 'object' && typeof module === 'object') module.exports = factory(); else if(typeof define === 'function' && define.amd) define([], factory); else { var a = factory(); for(var i in a) (typeof exports === 'object' ? exports : root)[i] = a[i]; } })(typeof self !== 'undefined' ? self : this, function() { return _entry_return_; // 此模块返回值,是入口 chunk 返回的值 });
从 webpack 3.1.0 开始,你可以将 library 指定为对象,用于给每个 target 起不同的:
output: { library: { root: "MyLibrary", amd: "my-library", commonjs: "my-common-library" }, libraryTarget: "umd" }
模块验证 library。
其他 Targets
libraryTarget: "jsonp" - 这将把入口起点的返回值,包裹到 jsonp 包装容器中
MyLibrary(_entry_return_);
你的 library 的依赖将由 externals 配置定义。
output.path
string
output 目录对应。
path: path.resolve(__dirname, 'dist/assets')
注意,[hash] 在参数中被替换为编译过程(compilation)的 hash。详细信息请查看指南 - 缓存。
output.pathinfo
boolean
告诉 webpack 在 bundle 中引入「所包含模块信息」的相关注释。此选项认值是 false,并且不应该用于生产环境(production),但是对阅读开发环境(development)中的(generated code)极其有用。
pathinfo: true
注意,这些注释也会被至经过 tree shaking 后的 bundle 中。
output.publicPath
string function
对于按需加载(on-demand-load)或加载外部资源(external resources)(如、等)来说,output.publicPath 是很重要的选项。如果指定了的值,则在加载这些资源时会收到 。
此选项指定在浏览器中所引用的「此目录对应的公开 URL」。相对 URL(relative URL) 会被相对于 HTML (或 <base> )解析。相对于服务的 URL(Server-relative URL),相对于协议的 URL(protocol-relative URL) 或绝对 URL(absolute URL) 也可是可能用到的,或者有时必须用到,例如:当将资源托管到 CDN 时。
该选项的值是以 runtime(运行时) 或 loader(载入时) 所创建的每个 URL 为前缀。因此,在多数情况下,此选项的值都会以/结束。
认值是空字符串 ""。
简单规则如下:output.path 中的 URL 以 HTML 为基准。
path: path.resolve(__dirname, "public/assets"),publicPath: "https://cdn.example.com/assets/"
对于这个配置:
publicPath: "/assets/",chunkFilename: "[id].chunk.js"
对于 chunk 请求,看起来像这样 /assets/4.chunk.js。
对于 HTML 的 loader 可能会像这样:
<link href="/assets/spinner.gif" />
或者在加载 CSS 的时:
background-image: url(/assets/spinner.gif);
webpack-dev-server 也会认从 publicPath 为基准,使用它来决定在哪个目录下启用服务,来访问 webpack 的。
注意,参数中的 [hash] 将会被替换为编译过程(compilation) 的 hash。详细信息请查看指南 - 缓存。
示例:
publicPath: "https://cdn.example.com/assets/", // CDN(总是 HTTPS 协议) publicPath: "//cdn.example.com/assets/", // CDN (协议相同) publicPath: "/assets/", // 相对于服务(server-relative) publicPath: "assets/", // 相对于 HTML publicPath: "../assets/", // 相对于 HTML publicPath: "", // 相对于 HTML (目录相同)
在编译时(compile time)无法知道的 publicPath 的情况下,可以留空,然后在入口(entry file)处使用 __webpack_public_path__,以便在运行时(runtime)进行动态设置。
__webpack_public_path__ = myRuntimePublicPath // 应用程序入口的其他部分
有关 __webpack_public_path__ 的更多信息,请查看。
outputurceMapFilename
string
此选项会向硬盘写入,只在 devtool 启用了 SourceMap 选项时才使用。
配置 source map 的命名方式。认使用 "[file].map"。
可以使用 #output-filename 中的 [name], [id], [hash] 和 [chunkhash] 替换符号。除此之外,还可以使用以下替换符号。[file] 占位符会被替换为原始的名。我们建议只使用 [file] 占位符,因为其他占位符在非 chunk (non-chunk files)的 SourceMap 时不起作用。
outputurcePrefix
string
bundle 中每行的前缀。
sourcePrefix: "\t"
注意,认情况下使用空字符串。使用一些缩进会看起来更美观,但是可能导致多行字符串中的问题。
这里没有必要它。
output.strictModuleExceptionHandling
boolean
如果模块是在 require 时抛出异常,告诉 webpack 从模块实例缓存(require.cache)中这个模块。
出于原因,认为 false。
当设置为 false 时,该模块不会从缓存中,这将造成仅在第一次 require 时抛出异常(会导致与 node.js 不兼容)。
例如,设想一下 module.js:
throw new Error("error");
将 strictModuleExceptionHandling 设置为 false,只有第 require 抛出异常:
// with strictModuleExceptionHandling = falserequire("module") // <- 抛出require("module") // <- 不抛出
相反,将 strictModuleExceptionHandling 设置为 true,这个模块所有的 require 都抛出异常:
// with strictModuleExceptionHandling = true require("module") // <- 抛出 require("module") // <- 仍然抛出
output.umdNamedDefine
boolean
当使用了 libraryTarget: "umd",设置:
umdNamedDefine: true
会对 UMD 的构建过程中的 AMD 模块进行命名。否则就使用匿名的 define。