输出 | Output

输出（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 webpackUniversalModuleDefinition(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

此选项决定了非入口(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。

启用 cross-origin 属性 加载 chunk。以下是可接收的值……

crossOriginLoading: false - 禁用跨源加载（默认）

crossOriginLoading: "anonymous"- 无需凭据即可启用跨源加载

crossOriginLoading: "use-credentials"- 使用凭据启用跨源加载

output.devtoolFallbackModuleFilenameTemplate

string | function(info)

当上面的模板字符串或函数产生重复时使用的备用内容。

参阅output.devtoolModuleFilenameTemplate。

output.devtoolLineToLine

boolean | object

避免使用此选项，因为它已被弃用，并且很快会被删除。

对所有或某些模块启用「行到行映射(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:///[resource-path]?[loaders]"

模板字符串(template string)中做以下替换（通过 webpack 内部的 ModuleFilenameHelpers）：

当使用一个函数，同样的选项要通过 info 参数并使用驼峰式(camel-cased)：

devtoolModuleFilenameTemplate: info => {
  return `webpack:///${info.resourcePath}?${info.loaders}`
}

如果多个模块产生相同的名称，使用 output.devtoolFallbackModuleFilenameTemplate 来代替这些模块。

output.filename

string

此选项决定了每个输出 bundle 的名称。这些 bundle 将写入到 output.path 选项指定的目录下。

对于单个入口起点，filename 会是一个静态名称。

filename: "bundle.js"

然而，当通过多个入口起点( entry point )、代码拆分( code splitting )或各种插件( plugin )创建多个 bundle，应该使用以下一种替换方式，来赋予每个 bundle 一个唯一的名称……

使用条目名称：

filename: "[name].bundle.js"

使用内部块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]TemplatedPathPlugin）：

[hash] 和 [chunkhash] 的长度可以使用 [hash:16]（默认为20）来指定。或者，通过指定output.hashDigestLength 在全局配置长度。

在使用 ExtractTextWebpackPlugin 时，可以用 [contenthash] 来获取提取文件的 hash（既不是 [hash] 也不是 [chunkhash]）。

output.hashDigest

在生成 hash 时使用的编码方式，默认为 'hex'。支持 Node.js hash.digest 的所有编码。

output.hashDigestLength

散列摘要的前缀长度，默认为 20。

output.hashFunction

散列算法，默认为 'md5'。支持 Node.JS crypto.createHash 的所有功能。从 4.0.0-alpha2 开始，hashFunction 现在可以是一个返回自定义 hash 的构造函数。出于性能原因，你可以提供一个不加密的哈希函数(non-crypto hash function)。

output.hashSalt

一个可选的加盐值，通过 Node.JS hash.update 来更新哈希。

output.hotUpdateChunkFilename

string

自定义热更新 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

自定义热更新的主文件名( 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; for libraryTarget: "umd"）

output.library 的值的作用，取决于output.libraryTarget 选项的值；完整的详细信息请查阅该章节。注意，output.libraryTarget 的默认选项是 var，所以如果使用以下配置选项：

output: {
  library: "MyLibrary"
}

如果生成的输出文件，是在 HTML 页面中作为一个 script 标签引入，则变量 MyLibrary 将与入口文件的返回值绑定。

有关output.library以及output.libraryTarget的更多信息，请参阅编写库指南指南。

output.libraryExport

string或string[]（自webpack 3.0.0以来）

默认： _entry_return_

通过 libraryTarget 配置将公开哪些模块或模块。

默认值_entry_return_是您的条目文件返回的命名空间或默认模块。

下面的例子演示了使用libraryTarget时这个配置的效果：“var”，但是可以使用任何目标。

支持以下配置：

libraryExport: "default"- 入口点的默认导出将分配给库目标：

// if your entry has a default export of `MyDefaultModule`
var MyDefaultModule = _entry_return_.default;

libraryExport: "MyModule"- 指定的模块将被分配给库目标：

var MyModule = _entry_return_.MyModule;

libraryExport: ["MyModule", "MySubModule"]- 该数组被解释为要分配给库目标的模块的路径：

var MySubModule = _entry_return_.MyModule.MySubModule;

正如示例所示，入口点的返回值受限于这些命名变量，因此生成的库的用法如下所示：

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_;

// In a separate 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_;

// In a separate script...
this.MyLibrary.doSomething(
MyLibrary.doSomething( // if this is 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 上下文没有关联。（更多详细信息，请阅读此 issue。）

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() {
  // This module return value is what your entry chunk returns
}

可以在 script 标签中，将 bundle 作为一个模块整体引入，并且可以像这样调用 bundle：

require(['MyLibrary'], function(MyLibrary) {
  // Do something with the library...
}

如果 output.library 未定义，将会生成以下内容。

define([], function() {
  // This module returns is what your entry chunk returns
}

如果直接加载 <script> 标签，此 bundle 无法按预期运行，或者根本无法正常运行（在 almond loader 中）。只能通过文件的实际路径，在 RequireJS 兼容的异步模块加载器中运行，因此在这种情况下，如果这些设置直接暴露在服务器上，那么 output.path 和 output.filename 对于这个特定的设置可能变得很重要。

libraryTarget: "umd" - 将你的 library 暴露为所有的模块定义下都可运行的方式。它将在 CommonJS, AMD 环境下运行，或将模块导出到 global 下的变量。了解更多请查看 UMD 仓库。

在这个例子中，你需要 library 属性来命名你的模块：

output: {
  library: "MyLibrary",
  libraryTarget: "umd"
}

最后的输出是：

(function webpackUniversalModuleDefinition(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(
})(this, function() {
  //what this module returns is what your entry chunk returns
}

注意，省略 library 会导致将入口起点返回的所有属性，直接赋值给 root 对象，就像对象分配章节。例如：

output: {
  libraryTarget: "umd"
}

输出将是：

(function webpackUniversalModuleDefinition(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];
  }
})(this, function() {
  //what this module returns is what your entry chunk returns
}

从 webpack 3.1.0 开始，你可以将 library 指定为一个对象，用于给每个 target 起不同的名称：

output: {
  library: {
    root: "MyLibrary",
    amd: "my-library",
    commonjs: "my-common-library"
  },
  libraryTarget: "umd"
}

模块证明库。

其他目标

libraryTarget: "jsonp" - 这将把入口点的返回值封装到一个jsonp包装器中。

MyLibrary(_entry_return_

您的库的依赖关系将由externals配置定义。

output.path

string

输出目录作为绝对路径。

path: path.resolve(__dirname, 'dist/assets')

请注意，[hash]在此参数中将被编译的散列替换。有关详细信息，请参阅缓存指南。

output.pathinfo

boolean

告诉 webpack 在 bundle 中引入「所包含模块信息」的相关注释。此选项默认值是 false，并且不应该用于生产环境(production)，但是对阅读开发环境(development)中的生成代码(generated code)极其有用。

pathinfo: true

注意，这些注释也会被添加至经过 tree shaking 后生成的 bundle 中。

output.publicPath

string

对于按需加载(on-demand-load)或加载外部资源(external resources)（如图片、文件等）来说，output.publicPath 是很重要的选项。如果指定了一个错误的值，则在加载这些资源时会收到 404 错误。

此选项指定在浏览器中所引用的「此输出目录对应的公开 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 (always HTTPS)
publicPath: "//cdn.example.com/assets/", // CDN (same protocol)
publicPath: "/assets/", // server-relative
publicPath: "assets/", // relative to HTML page
publicPath: "../assets/", // relative to HTML page
publicPath: "", // relative to HTML page (same directory)

在编译时(compile time)无法知道输出文件的 publicPath 的情况下，可以留空，然后在入口文件(entry file)处使用自由变量(free variable) __webpack_public_path__，以便在运行时(runtime)进行动态设置。

 __webpack_public_path__ = myRuntimePublicPath

// rest of your application entry

有关 __webpack_public_path__ 的更多信息，请查看此讨论。

output.sourceMapFilename

string

此选项会向硬盘写入一个输出文件，只在 devtool 启用了 SourceMap 选项时才使用。

配置如何命名源映射。默认"[file].map"已经使用。

可以使用 #output-filename 中的 [name], [id], [hash] 和 [chunkhash] 替换符号。除此之外，还可以使用以下替换符号。[file] 占位符会被替换为原始文件的文件名。我们建议__只使用 [file] 占位符__，因为其他占位符在非 chunk 文件(non-chunk files)生成的 SourceMap 时不起作用。

output.sourcePrefix

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 = false
require("module") // <- throws
require("module") // <- doesn't throw

相反，将 strictModuleExceptionHandling 设置为 true，这个模块所有的 require 都抛出异常：

// with strictModuleExceptionHandling = true
require("module") // <- throws
require("module") // <- also throw

output.umdNamedDefine

boolean

当使用了 libraryTarget: "umd"，设置：

umdNamedDefine: true

会对 UMD 的构建过程中的 AMD 模块进行命名。否则就使用匿名的 define。