webpack入門（三）——webpack 配置

阿新 • • 發佈：2019-01-02

喂一個配置物件給webpack ，它就可以幹活兒了。根據你用webpack的用法，有兩種途徑傳入這個物件：

CLI( 命令列)

如果你用命令列，命令列會讀取一個叫webpack.config.js（或者用 –config 選項傳入的一個配置檔案）的檔案。這個檔案應該匯出一個配置物件，如下：

module.exports = {
    // configuration
};

node.js API

如果你用node.js API，你需要把配置檔案作為一個引數，傳給webpack。如下：

webpack({
    // configuration
}, callback);

混合配置

在兩種情況下，你都可以用一個配置物件的陣列，它們是並行程序的。它們共用檔案系統的快取和監控，所以這是一種比多次呼叫webpack更高效的辦法。

config 物件內容

提示：記住你不需要寫純粹的JSON到配置檔案中。javascript隨便用。webpack只是一個node.js 模組…

一個最簡單的配置物件如下：

{
    context: __dirname + "/app",
    entry: "./entry",
    output: {
        path: __dirname + "/dist",
        filename: "bundle.js" 

    }
}

下面開始解釋這些配置項了。

context

這是entry配置項的根目錄（絕對路徑）。如果output.pathinfo也設定了，它的pathinfo是基於這個根目錄。

entry

包的入口。
如果你傳入一個字串：這個字串作為主模組的啟動點。（本句翻譯待考）
如果你傳入一個數組，陣列中所有模組都會啟動，但最後一個會被匯出。

entry:["./entry1","./engtry2"]

如果你傳入一個物件：會建立多個入口包。key就是塊（chunk）名字。value就是一個字串或者一個數組。

{
    entry: {
        page1: "./page1" 
,
        page2: ["./entry1", "./entry2"]
    },
    output: {
        // Make sure to use [name] or [id] in output.filename
        //  when using multiple entry points
        filename: "[name].bundle.js",
        chunkFilename: "[id].bundle.js"
    }
}

注意：你不可能在其它配置項中設定入口點。如果你需要特殊配置入口點，你需要用到上面提到的混合配置。

output

影響編譯輸出的配置項。 output配置項告訴webpack怎麼把編譯後的檔案寫入磁碟。注意，如果用多入口配置，只會一個能被指定output。

如果你用了hshing([hash]或者[chunkhash])，請先確保有一個指定的模組排序。用OccurrenceOrderPlugin 或者 recordsPath。

output.filename

指定每一個輸出檔案的存檔檔名。這裡你不必指定絕對路徑。output.path才是用來指定檔案路徑的配置項。filename 是單獨給檔案命名的。

單入口

{
  entry: './src/app.js',
  output: {
    filename: 'bundle.js',
    path: './built'
  }
}

// writes to disk: ./built/bundle.js

多入口
如果你的配置建立了多個“塊”（多入口點或者用了像CommonsChunkPlugin），你應該換成下面這樣的配置來確保每一個檔案都有一個特有的檔名。
[name] 會被塊名替換掉。
[hash]會被編譯的hash替換掉。
[chunkhash]會被塊的hash替換掉。

{
  entry: {
    app: './src/app.js',
    search: './src/search.js'
  },
  output: {
    filename: '[name].js',
    path: __dirname + '/built'
  }
}

// writes to disk: ./built/app.js, ./built/search.js

output.path

輸出目錄，必須是絕對路徑。
[hash]會被編譯hash替換掉。

output.publicPath

當瀏覽器需要引用輸入出文件時，這個配置項指定輸入檔案的公共URL地址。在loader中它被嵌入到script 或者 link 標籤或者對靜態資源的引用裡。當檔案的href 或者 url()與它在磁碟上的路徑不一致時publicPath ，就應當用·publicPath (像path一樣指定) ，這在你想定義把一些或者所有檔案放在不同的主機或CDN上時會非常有用。webpack dev server 也是用publicpath決定輸出檔案從哪裡公開。和 path 一樣，你可以用 [hash] 替換快取檔案。
config.js

output: {
    path: "/home/proj/public/assets",
    publicPath: "/assets/"
}

index.html

<head>
  <link href="/assets/spinner.gif"/>
</head>

一個更加複雜的例子，使用CDN和hash 資源。

config.js

output: {
    path: "/home/proj/cdn/assets/[hash]",
    publicPath: "http://cdn.example.com/assets/[hash]/"
}

注意：如果最終的 publicPath 不能確定在編譯時不能確定，你可以留白在執行時在入口檔案中動態設定。如果在編譯時不知道publicPath你可以忽略它並設定在入口檔案中設定 __webpack_public_path__。

__webpack_public_path__ = myRuntimePublicPath

// rest of your application entry

output.chunkFilename

它是 output.path 目錄中作為相對路徑的非入口chunk的檔名。
[id] 會被chunk的id替換掉。
[name] 會被chunk的name替換掉（如果沒有名字，會被id替換）。
[hash] 會被編譯的hash替換掉。
[chunkhash] 會被 chunk hash替換掉。

output.sourceMapFilename

javascript 的sourceMap檔案的檔名。它會被放在 output.path 目錄下。
[file] 會被javascript的檔名替換掉。
[id] 會被 chunk id替換掉。
[hash] 會被編譯hash替換掉。

Default: “[file].map”

output.devtoolModuleFilenameTemplate

在 sourceMap中生成source array是用函式來做的。這個配置項就是這個函式所在的檔名模板字元。
[resource] 會被webapck 用來解析檔案的路徑替換掉，如果有Loader也包括loader最右邊的query引數。
[resource-path]] 跟 resource配置項一樣，只是不會帶query引數。
[loaders] loader列表，帶最右邊的引數（明確的Loader）。
[[all-loaders] loader列表，帶最右邊的引數（包括自然生效的loader）。
[id] 會被模組id替換掉。
[hash] 會被模組唯一識別符號替換。
[hash] 會被檔案的絕對路徑檔名替換。

也可以定義為一個函式而不是字串模板。這個函式會接收 info 物件，這個Info物件曝露了一下屬性：
1. identifier
2. shortIdentifier
3. resource
4. resourcePath
5. absoluteResourcePath
6. allLoaders
7. query
8. moduleId
9. hash

output.devtoolFallbackModuleFilenameTemplate

跟 output.devtoolModuleFilenameTemplate 很像。但是是用在混合模組兒標識中。

Default: “webpack:///[resourcePath]?[hash]”

output.devtoolLineToLine

能給所有或者指定模組設定為行到行的map模式。行到行map模式用一個簡單的 sourcecMap , 在這個sourceMap 中每行生成的檔案對映到同一行的原始檔。這是一個性能優化。只有當你需要更好的效能或者你確定輸入的行和生成的行匹配，你再這麼做。
true 使它對所有module有效（不推薦）。
一個物件{test，include,exclude} 同module.loaders 很像，對指定的檔案設定有效。

Default:disabled

output.hotUpdateChunkFilename

熱更新的Chunk 檔名。他們在 output.path 目錄中。
[id] 會被chunk的id替換掉。
[hash] 會被編譯的hash替換掉。（最後一次的hash會被儲存在記錄中）

Default: “[hash].hot-update.json”

output.jsonpFunction

webpack用來非同步載入chunk的JSONP 函式。
一個小函式或許可以減少一點檔案的大小。當一個單頁面上有多個webpack例項時，使用不同的識別符號。

Default: “webpackJsonp”

output.hotUpdateFunction

webpack用來非同步載入熱替換chunk的JSONP 函式。

Default: “webpackHotUpdate”

output.pathinfo

如果設定了，將包匯出為庫。 output.library 就是庫的名字。
如果你寫了一個單庫，並且想把它以單檔案形式釋出的話，可以用它。

output.libraryTarget

格式化匯出庫。
"var" 通過設定一個變數匯出：var Library =xxx (預設)

"this" 通過設定一個this的屬性匯出：var Library =xxx

"commonjs" 通過設定一個exports 的一個屬性匯出: exports["Library"] = xxx

"commonjs2" 通過設定一個module.exports 匯出: module.exports=xxx

"amd" 匯出到AMD(隨便命名 -通過library選項來設定名稱)

"umd" 匯出到AMD，CommonJS2或者作為root的一個屬性。

Default: “var”
如果 output.library 沒設定，但是output.library 設定了除var以外的值，exports物件的每一個屬性都會被複制（除了amd,commonjs2和umd）

output.umdNamedDefine

如果 output.libraryTarget 設定為umd 而且output.library 也設定了。這個設為true，將為AMD模組命名。

output.sourcePrefix

給bundle資源的每一行前面加上這個字串。

Default: “\t”

output.crossOriginLoading

這一項的設定可以允許跨域載入 chunks。
可能的值為：
false 不允許跨域載入。
anonymous 啟用跨域載入。當用anonymous 時，請求中沒有安全證書傳送。
use-credentials 啟用跨域載入。請求中安全證書會發送。

Default: false

module

影響正常模組的選項

module.loaders

一個自動運用的 loader陣列。
每一個都可以有以下幾個屬性。
* test :一個必須滿足的條件
* exclude : 一個排除的條件
* include : 要用Loader轉換的匯入檔案的路徑陣列。
* loader : 一個用“！”隔開 loader的字串。
* loaders : 一個loader字串的陣列。

一個條件可以是正則表示式(tested against absolute path)，或者是一個包含絕對路徑的字串，或者一個函式function(absPath): bool ，或者一個數組用“and”連線這些的陣列。

重要：這裡Loader的resolved相對於它們應用的的資源的路徑。這意味著它們不是相對配置檔案的路徑。如果你已經用npm 安裝過loader而且你的 node_ｍoudles資料夾不在所有原始檔的父資料夾中，webpack會找不到 loader.你需要新增 node-modules資料夾,作為 resolveLoader.root 選項的絕對路徑。
例如：

module: {
  loaders: [
    {
      // "test" is commonly used to match the file extension
      test: /\.jsx$/,

      // "include" is commonly used to match the directories
      include: [
        path.resolve(__dirname, "app/src"),
        path.resolve(__dirname, "app/test")
      ],

      // "exclude" should be used to exclude exceptions
      // try to prefer "include" when possible

      // the "loader"
      loader: "babel-loader"
    }
  ]
}

module.preLoaders, module.postLoaders

語法跟 module.loaders 一樣。
一個在運用loader之前（後）的loader陣列。

resolve

影響模組的解決方案。

resolve.alias

用其它模組或者路徑替換一個模組。
預期是一個物件，這個物件的key是模組的名稱，value是一個新的path。它類似於一個替換，但更聰明一點。
如果key 以結尾,只有精確的部分（不包括）會被替換掉。
如果value 是一個相對路徑，模組將與包含它的檔案的路徑有關。

alias	require(“xyz”)	require(“xyz/file.js”)
{}	/abc/node_modules/xyz/index.js	/abc/node_modules/xyz/file.js
{ xyz: “/absolute/path/to/file.js” }	/absolute/path/to/file.js	/abc/node_modules/xyz/file.js
{ xyz$: “/absolute/path/to/file.js” }	/absolute/path/to/file.js	error
{ xyz: “./dir/file.js” }	/abc/dir/file.js	/abc/node_modules/xyz/file.js
{ xyz$: “./dir/file.js” }	/abc/dir/file.js	error
{ xyz: “/some/dir” }	/some/dir/index.js	/some/dir/file.js

如果在package.json中有定義入口檔案，index.js或許會被查到到其它檔案。

resolve.root

包含你的模組的目錄（絕對路徑）。也可能是目錄的陣列。需要將單個目錄新增到搜尋路徑的情況下，才用這個設定。

注意：它必須是絕對路徑，請不要傳像./app/modules 這樣的相對路徑。
例：

var path = require('path');

// ...
resolve: {
  root: [
    path.resolve('./app/modules'),
    path.resolve('./vendor/modules')
  ]
}

resolve.modulesDirectories

一個目錄陣列。這個目錄將解析給當前目錄以及它的祖先目錄，在這裡查詢模組。它的功能類似於 node 的 node_modules目錄。例如，如果把它設定為["mydir"],webpack 會查詢“./mydir”,”../mydir”,”../../mydir”等。

預設值為：["web_modules", "node_modules"]
注意：在這裡，不必要傳入像"../someDir", "app", "." 或者絕對路徑之類的值。只需要用一個目錄名，不要用路徑。當你的層次結構中有這個資料夾時再用這個，要不然你最好是用 resolve.root 選項。

resolve.fallback

一個目錄(或者目錄絕對目錄的陣列)。如果webpack 在 resolve.root 或者 resolve.modulesDirectories 實在找不到某個模組了，會去這個（些）目錄中找。

resolve.extensions

一個包含模組副檔名的陣列。例如，為了發現CoffeeScript 檔案，你的陣列應該包含字串".coffee"。

Default: ["", ".webpack.js", ".web.js", ".js"]
注意：設定了這個選項，會取代預設的模組副檔名。重要的事情說三遍：意味著webpack不再用預設副檔名查詢模組，意味著webpack不再用預設副檔名查詢模組，意味著webpack不再用預設副檔名查詢模組。如果你想正確載入一個帶有副檔名的模組，你必須把一個空字串放在你的數組裡。如果你想不要副檔名來載入一個js檔案，你需要將“.js”加入你的陣列。

resolve.packageMains

在package.json中查詢符合這些欄位的檔案

Default: [“webpack”, “browser”, “web”, “browserify”, [“jam”, “main”], “main”]

resolve.packageAlias

在package.json中查詢物件裡的欄位，鍵值對是按照這個規範的別名來進行的

Not set by default

比如”browser”會檢查browser欄位

resolve.unsafeCache

啟用不安全的快取來解析一部分檔案。改變快取路徑也許會導致出錯（罕見情況下）。一個正則表示式數組裡，只有一個正則或只有一個為true（對應全部檔案）是最好的實踐。如果解析路徑匹配，就會被快取。

Default: []

resolveLoader

跟 resolve很像，但是是為loaders準備的。

// Default:
{
    modulesDirectories: ["web_loaders", "web_modules", "node_loaders", "node_modules"],
    extensions: ["", ".webpack-loader.js", ".web-loader.js", ".loader.js", ".js"],
    packageMains: ["webpackLoader", "webLoader", "loader", "main"]
}

注意，你可以用alias，其他特性和resolve相似。例如設定了alias中的{txt: ‘raw-loader’｝， txt!templates/demo.txt 結果會用 raw-loader解析。

resolveLoader.moduleTemplates

這是resolveLoader 唯一的屬性。它描述了嘗試的模組名稱的替代名

Default: [“-webpack-loader”, “-web-loader”, “-loader”, ““]

externals

指定的依賴不會被webpack解析，但會成為bundle裡的依賴。output.libraryTarget.決定著依賴的型別。值是物件，字串，函式，正則，陣列都會被接受。

字串：一個精確匹配的依賴會變成externals依賴，同一字串會被用於externals依賴。
物件：如果依賴精確匹配到了物件的一個屬性，屬性值就會被當作externals依賴。屬性值可以包含一個依賴型的字首，用一個空格隔開。如果屬性值為true，則使用該屬性名。如果屬性值為false，外部測試失敗，這個依賴是內部依賴。見下面的例子。

函式：function(context, request, callback(err, result))。函式會在每個依賴中呼叫。如果結果被傳遞到回撥函式裡，這個值就會被像處理物件屬性值那樣處理。

正則表示式：每個被匹配的依賴都會成為外部依賴。匹配的文字會被用作外部依賴的請求。因為請求是用於生成外部程式碼鉤子的確切程式碼，如果你匹配到一個cmd的包(比如 ‘../some/package.js’),相反使用外部function的策略。你可以通過callback(null, “require(‘” + request + “’)”引入包，這個包生成module.exports = require(‘../some/package.js’);使用要求在webpack上下文外。

陣列：這個表的多個值(遞迴)

{
    output: { libraryTarget: "commonjs" },
    externals: [
        {
            a: false, // a is not external
            b: true, // b is external (require("b"))
            "./c": "c", // "./c" is external (require("c"))
            "./d": "var d" // "./d" is external (d)
        },
        // Every non-relative module is external
        // abc -> require("abc")
        /^[a-z\-0-9]+$/,
        function(context, request, callback) {
            // Every module prefixed with "global-" becomes external
            // "global-abc" -> abc
            if(/^global-/.test(request))
                return callback(null, "var " + request.substr(7));
            callback();
        },
        "./e" // "./e" is external (require("./e"))
    ]
}

type	value	resulting import code
“var”	“abc”	module.exports = abc;
“var”	“abc.def”	module.exports = abc.def;
“this”	“abc”	(function() { module.exports = this[“abc”]; }());
“this”	[“abc”, “def”]	(function() { module.exports = this[“abc”][“def”]; }());
“commonjs”	“abc”	module.exports = reqaluire(“abc”);
“commonjs”	[“abc”, “def”]	module.exports = require(“abc”).def;
“amd”	“abc”	define([“abc”], function(X) { module.exports = X; })
“umd”	“abc”	everything above

如果沒有作為amd/umd的目標解析，將會用一個external 值強制執行amd或者umd。

注意，如果用umd你可以指定一個物件的額外值，屬性為 commonjs, commonjs2, amd和root會被設定不同的值。

target

“web” 在瀏覽器中使用的編譯環境（預設值）
“webworker” 被作為webworker編譯
“node” 在nodejs環境下編譯(用require載入chunks)
“async-node” 在nodejs環境下編譯(用fs和vm非同步載入chunks)
“node-webkit” 在webkit下使用jsonp載入chunk，也支援在node中加入require(“nw.gui”) （實驗性質）
“electron” 為 Electron 編譯。
“electron-renderer” 為 Electron 渲染程序編譯。

bail

報告第一個錯誤為硬性錯誤，不可忽略。

profile

定時在每個模組捕捉資訊。

提示，用analyze tool讓它視覺化，–json 或者 stats.toJson()會給你JSON的統計。

cache

快取生成模組和和chunks來提高混合增l量編譯時的效能。
啟用watch模式會預設啟動它。
可以傳入 false禁用它。
你可以傳遞一個物件啟用它並且讓webpack把傳遞的物件作為快取。用這種辦法，你可以在混合編譯器的編譯回撥中共享快取。注意：不要在多配置的回撥中共享快取。

debug

把loader的模式切到debug。

devtool

選一個開發工具來加快除錯

eval 每個模組都用eval執行
source-map 觸發SourceMap，詳情看output.sourceMapFilename
hidden-source-map 同上，但不會在包中新增引用註釋。
inline-source-map SourceMap被作為dataurl加入到js檔案中。
eval-source-map 每個模組都用eval執行，並且SourceMap被作為dataurl加入到eval中。
cheap-source-map 沒有對映的sourcemap，loaders的sourcemap不會啟用。
cheap-module-source-map 沒有對映的sourcemap，sourcemap就簡單的對映到每一行。

@,#或者#@字首將強行顯示編譯指示。（[email protected]版本中預設用@，[email protected]版本中預設用#，建議用#）
例如： cheap-module-inline-source-map, cheap-eval-source-map, #@source-map

如果你的模組已經包含了sourcemap，你需要用source-map-loader合併被觸發的sourcemap

devtool	打包速度	二次打包速度	是否建議生產中使用	特點｜
eval	+++	+++	否	生成程式碼
cheap-eval-source-map	+	++	否	轉化程式碼（一行）
cheap-source-map	+	o	是	轉化程式碼（一行）
cheap-module-eval-source-map	o	++	否	原始碼（一行）
cheap-module-source-map	o	-	是	原始碼（一行）
eval-source-map	-	+	否	原始碼
source-map	-	-	是	原始碼

例如：

{
    devtool: "#inline-source-map"
}
// =>
//# sourceMappingURL=...

注意，下一個大的版本預設加-d，將會變為cheap-module-eval-source-map。

devServer

當這個webpack config 傳給webpack-dev-server命令列時，這個選項用來配置 webpack-dev-server的一些行為。
例如

{
    devServer: {
        contentBase: "./build",
    }
}

node

為不同節點包含polufills或者mocks。

console: true or false
global: true or false
process: true, “mock” or false
__filename: true (real filename), “mock” (“/index.js”) or false
__dirname: true (real dirname), “mock” (“/”) or false
< node buildin >: true, “mock”, “empty” or false

// Default:
{
   console: false,
   global: true,
   process: true,
   Buffer: true,
   __filename: "mock",
   __dirname: "mock",
   setImmediate: true
}

amd

設定require.amd和 define.amd的值
例如： amd:{jquery:true} （為舊的 1.x AMD版本的jQuery）

loader

在loader上下文中可以自定義。

recordsPath, recordsInputPath, recordsOutputPath

從一個JSON檔案中存入或者讀取編譯器 state。這將導致模組或chunk的id持久化。
期望是絕對路徑，recordsPath 被用於recordsInputPath 和recordsOutputPath，如果他倆未定義。
當使用熱替換之間的多個呼叫編譯器的時候，這個選項是必須的。

plugins

向編譯器新增額外的外掛。