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
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。
啟用 cross-origin 屬性 加載 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 內部的 ModuleFilenameHelpers
):
當使用一個函數,同樣的選項要通過 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
]TemplatedPathPlugin
):
?
后面的字符串
[hash]
和 [chunkhash]
的長度可以使用 [hash:16]
(默認為20)來指定。或者,通過指定output.hashDigestLength
在全局配置長度。
如果將這個選項設為一個函數,函數將返回一個包含上面表格中替換信息的對象。
output.hashDigest
在生成 hash 時使用的編碼方式,默認為 'hex'
。支持 Node.js hash.digest
的所有編碼。
output.hashDigestLength
散列摘要的前綴長度,默認為 20
。
output.hashFunction
string|function
散列算法,默認為 'md5'
。支持 Node.JS crypto.createHash
的所有功能。從 4.0.0-alpha2
開始,hashFunction
現在可以是一個返回自定義 hash 的構造函數。出於性能原因,你可以提供一個不加密的哈希函數(non-crypto hash function)。
hashFunction: require('metrohash').MetroHash64
確保 hash 函數有可訪問的 update
and digest
方法。
output.hashSalt
一個可選的加鹽值,通過 Node.JS hash.update
來更新哈希。
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
將與入口文件的返回值綁定。
output.libraryExport
string
or string[]
(since webpack 3.0.0)
Default:
_entry_return_
Configure 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 config when using libraryTarget: "var"
, but any target may be used.
The following configurations 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
configurations specified above, the resulting libraries could 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 上下文沒有關聯。(更多詳細信息,請 閱讀此 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() { 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 下的變量。了解更多請查看 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(); })(typeof self !== 'undefined' ? self : this, function() { return _entry_return_; // 此模塊返回值,是入口 chunk 返回的值 });
注意,省略 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]; } })(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 是很重要的選項。如果指定了一個錯誤的值,則在加載這些資源時會收到 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(總是 HTTPS 協議) publicPath: "//cdn.example.com/assets/", // CDN (協議相同) publicPath: "/assets/", // 相對於服務(server-relative) publicPath: "assets/", // 相對於 HTML 頁面 publicPath: "../assets/", // 相對於 HTML 頁面 publicPath: "", // 相對於 HTML 頁面(目錄相同)
在編譯時(compile time)無法知道輸出文件的 publicPath
的情況下,可以留空,然后在入口文件(entry file)處使用自由變量(free variable) __webpack_public_path__
,以便在運行時(runtime)進行動態設置。
__webpack_public_path__ = myRuntimePublicPath // 應用程序入口的其他部分
有關 __webpack_public_path__
的更多信息,請查看此討論。
output.sourceMapFilename
string
此選項會向硬盤寫入一個輸出文件,只在 devtool
啟用了 SourceMap 選項時才使用。
配置 source map 的命名方式。默認使用 "[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") // <- 拋出 require("module") // <- 不拋出
相反,將 strictModuleExceptionHandling
設置為 true
,這個模塊所有的 require
都拋出異常:
// with strictModuleExceptionHandling = true require("module") // <- 拋出 require("module") // <- 仍然拋出
output.umdNamedDefine
boolean
當使用了 libraryTarget: "umd"
,設置:
umdNamedDefine: true
會對 UMD 的構建過程中的 AMD 模塊進行命名。否則就使用匿名的 define
。