Webpack：命令行接口（CLI）

為了更合適且方便地使用配置，可以在 webpack.config.js 中對(duì) webpack 進(jìn)行配置。CLI 中傳入的任何參數(shù)會(huì)在配置文件中映射為對(duì)應(yīng)的參數(shù)。

如果你還沒(méi)有安裝過(guò) webpack 和 CLI，請(qǐng)先閱讀安裝指南。

命令

webpack-cli 提供了許多命令來(lái)使 webpack 的工作變得更簡(jiǎn)單。默認(rèn)情況下，webpack 提供了以下命令：

Command	Usage	Description
build	build|bundle|b [entries...] [options]	Run webpack (default command, can be omitted).
configtest	configtest|t [config-path]	Validate a webpack configuration.
help	help|h [command] [option]	Display help for commands and options.
info	info|i [options]	Outputs information about your system.
init	init|create|c|new|n [generation-path] [options]	Initialize a new webpack project.
loader	loader|l [output-path] [options]	Scaffold a loader.
plugin	plugin|p [output-path] [options]	Scaffold a plugin.
serve	serve|server|s [options]	Run the webpack-dev-server.
version	version|v [commands...]	Output the version number of webpack, webpack-cli and webpack-dev-server.
watch	watch|w [entries...] [options]	Run webpack and watch for files changes.

Build

運(yùn)行 webpack（默認(rèn)命令，可用輸出文件）。

npx webpack build [options]

示例

npx webpack build --config ./webpack.config.js --stats verbose

Init

用于初始化一個(gè)新的 webpack 項(xiàng)目。

npx webpack init [generation-path] [options]

示例

npx webpack init ./my-app --force --template=default

生成路徑

生成配置的位置。默認(rèn)為 process.cwd()。

配置

-t, --template

string = 'default'

要生成的模板名稱。

-f, --force

boolean

不輸入配置項(xiàng)就生成一個(gè)項(xiàng)目。該配置啟用時(shí)所有命令行配置項(xiàng)將使用默認(rèn)值。

Loader

初始化一個(gè) loader。

npx webpack loader [output-path] [options]

示例

npx webpack loader ./my-loader --template=default

Output Path

輸出文件夾，例如 ./loader-name。

Options

-t, --template

string = 'default'

模板類型。

Plugin

初始化一個(gè)插件。

npx webpack plugin [output-path] [options]

示例

npx webpack plugin ./my-plugin --template=default

Output Path

輸出文件夾，例如 ./plugin-name.

Options

-t, --template

string = 'default'

模板類型。

Info

輸出你的系統(tǒng)信息。

npx webpack info [options]

示例

npx webpack info --output json --addition-package postcss

info 配置項(xiàng)

-a, --additional-package

string

在輸出信息中添加額外的包。

example

npx webpack info --additional-package postcss

-o, --output

string : 'json' | 'markdown'

獲取指定格式的輸出。

示例

npx webpack info --output markdown

Configtest

校驗(yàn) webpack 配置。

npx webpack configtest [config-path]

示例

npx webpack configtest ./webpack.config.js

Config Path

你的 webpack 配置文件路徑。默認(rèn)為 ./webpack.config.js。

Serve

運(yùn)行 webpack 開(kāi)發(fā)服務(wù)器。

npx webpack serve [options]

示例

npx webpack serve --static --open

Watch

運(yùn)行 webpack 并且監(jiān)聽(tīng)文件變化。

npx webpack watch [options]

示例

npx webpack watch --mode development

Flags

默認(rèn)情況下，webpack 提供了以下 flag：

Flag / 別名	類型	描述
--entry	string[]	應(yīng)用程序的入口文件，例如 ./src/main.js
--config, -c	string[]	提供 webpack 配置文件的路徑，例如 ./webpack.config.js
--config-name	string[]	要使用的配置名
--name	string	配置名稱，在加載多個(gè)配置時(shí)使用
--color	boolean	啟用控制臺(tái)顏色
--merge, -m	boolean	使用 webpack-merge 合并兩個(gè)配置文件，例如 -c ./webpack.config.js -c ./webpack.test.config.js
--env	string[]	當(dāng)它是一個(gè)函數(shù)時(shí)，傳遞給配置的環(huán)境變量
--progress	boolean, string	在構(gòu)建過(guò)程中打印編譯進(jìn)度
--help	boolean	輸出所有支持的 flag 和命令
--output-path, -o	string	webpack 生成文件的輸出位置，例如 ./dist
--target, -t	string[]	設(shè)置要構(gòu)建的 target
--watch, -w	boolean	監(jiān)聽(tīng)文件變化
--watch-options-stdin	boolean	stdin stream 結(jié)束時(shí)，停止監(jiān)聽(tīng)
--hot, -h	boolean	啟用 HMR
--devtool, -d	string	控制是否生成 source map，以及如何生成
--prefetch	string	預(yù)先發(fā)生請(qǐng)求
--json, -j	boolean, string	將結(jié)果打印成 JSON 格式或存儲(chǔ)在文件中
--mode	string	定義 webpack 所需的 mode
--version, -v	boolean	獲取當(dāng)前 cli 版本
--stats	boolean, string	它告訴 webpack 如何處理 stats
--analyze	boolean	它調(diào)用 webpack-bundle-analyzer 插件來(lái)獲取 bundle 信息

Negated Flags

Flag	描述
--no-color	禁用控制臺(tái)顏色
--no-hot	如果你通過(guò)配置啟用了 HMR，則禁用它
--no-stats	禁用任何由 webpack emit 出來(lái)的 stats
--no-watch	禁用文件變更的監(jiān)聽(tīng)
--no-devtool	禁止生成 source maps

核心 Flags

從 CLI v4 和 webpack v5 開(kāi)始，CLI 將采用從 webpack 的 core 中導(dǎo)入整個(gè)配置的模式，允許 CLI 調(diào)整幾乎所有配置項(xiàng)。

鏈接中是 webpack v5 和 CLI v4 支持的所有核心 flag 列表 - 詳戳

例如，如果你想在項(xiàng)目中啟用性能提示，你需在配置中使用此選項(xiàng)，而如果使用核心 flag，你可以這樣做：

npx webpack --performance-hints warning

用法

使用配置文件

npx webpack [--config webpack.config.js]

配置文件中的相關(guān)選項(xiàng)，請(qǐng)參閱配置。

不使用配置文件

npx webpack --entry <entry> --output-path <output-path>

示例

npx webpack --entry ./first.js --entry ./second.js --output-path /build

entry

構(gòu)建項(xiàng)目時(shí)入口可以配置一個(gè)文件名或一組被命名過(guò)的文件名。你可以傳遞多個(gè)入口（每個(gè)入口在啟動(dòng)時(shí)加載）。 如下是通過(guò) CLI 指定 entry 的多種方式：

npx webpack ./first-entry.js

npx webpack --entry ./first-entry.js

npx webpack ./first-entry.js ./other-entry.js

npx webpack --entry ./first-entry.js ./other-entry.js

output-path

用于存儲(chǔ)構(gòu)建后的文件路徑。它將映射到配置選項(xiàng) output.path。

示例

假設(shè)你的項(xiàng)目結(jié)構(gòu)像下面這樣：

├── dist
├── index.html
└── src
    ├── index.js
    ├── index2.js
    └── others.js

npx webpack ./src/index.js --output-path dist

這將對(duì)源碼進(jìn)行打包，其入口為 index.js，且 bundle 文件的輸出路徑為 dist。

asset main.js 142 bytes [compared for emit] [minimized] (name: main)
./src/index.js 30 bytes [built] [code generated]
./src/others.js 1 bytes [built] [code generated]
webpack 5.1.0 compiled successfully in 187 ms

npx webpack ./src/index.js ./src/others2.js --output-path dist/

以多個(gè)入口的方式打包文件

asset main.js 142 bytes [compared for emit] [minimized] (name: main)
./src/index.js 30 bytes [built] [code generated]
./src/others2.js 1 bytes [built] [code generated]
./src/others.js 1 bytes [built] [code generated]
webpack 5.1.0 compiled successfully in 198 ms

默認(rèn)配置

CLI 會(huì)在你的項(xiàng)目路徑中尋找默認(rèn)配置，以下是 CLI 采集到的配置文件。

此處按順序遞增進(jìn)行優(yōu)先級(jí)查詢：

示例 —— 配置文件的查找順序 .webpack/webpackfile > .webpack/webpack.config.js > webpack.config.js

'webpack.config',
'.webpack/webpack.config',
'.webpack/webpackfile',

通用配置

help

列出命令行可用的基礎(chǔ)命令和 flag

通過(guò) webpack help [command] [option] 以及 webpack [command] --help 均可獲得幫助信息：

npx webpack --help

# or

npx webpack help

列出所有 cli 支持的命令和 flag

npx webpack --help=verbose

查看特定命令或選項(xiàng)的幫助：

npx webpack help --mode

version

顯示已安裝的 package 以及子 package 的版本。

如需檢查你正在使用的 webpack 和 webpack-cli 的版本，只需運(yùn)行如下命令：

npx webpack --version

# or

npx webpack version

運(yùn)行結(jié)果如下：

webpack 5.31.2
webpack-cli 4.6.0

若已安裝 webpack-dev-server，其版本信息會(huì)一并輸出：

webpack 5.31.2
webpack-cli 4.6.0
webpack-dev-server 3.11.2

如需檢查 webpack-cli 子包的版本（如 @webpack-cli/info），只需運(yùn)行如下命令：

npx webpack info --version

運(yùn)行結(jié)果如下：

@webpack-cli/info 1.2.3
webpack 5.31.2
webpack-cli 4.6.0
webpack-dev-server 3.11.2

config

使用配置文件進(jìn)行構(gòu)建

配置文件默認(rèn)為 webpack.config.js，還可以指定其它的配置文件。

npx webpack --config example.config.js

config-name

如果你的配置文件導(dǎo)出了多個(gè)配置，你可以使用 --config-name 來(lái)指定要運(yùn)行的配置。

如果你的 webpack.config.js 如下：

module.exports = [
  {
    output: {
      filename: './dist-first.js',
    },
    name: 'first',
    entry: './src/first.js',
    mode: 'development',
  },
  {
    output: {
      filename: './dist-second.js',
    },
    name: 'second',
    entry: './src/second.js',
    mode: 'development',
  },
  {
    output: {
      filename: './dist-third.js',
    },
    name: 'third',
    entry: './src/third.js',
    mode: 'none',
    stats: 'verbose',
  },
];

并且只想運(yùn)行第二個(gè)配置項(xiàng)：

npx webpack --config-name second

你也可以傳遞多個(gè)值來(lái)實(shí)現(xiàn)：

npx webpack --config-name first --config-name second

merge

你可以通過(guò) --merge 選項(xiàng)來(lái)合并兩個(gè)或多個(gè)不同的 webpack 配置：

npx webpack --config ./first.js --config ./second.js --merge

json

以 JSON 格式輸出 webpack 的運(yùn)行結(jié)果

npx webpack --json

如果你想把 stats 數(shù)據(jù)存儲(chǔ)為 JSON 而非輸出，你可以使用：

npx webpack --json stats.json

在其他情況下，webpack 會(huì)打印出 bundle、chunk 以及 timing 細(xì)節(jié)的 stats 信息。使用此選項(xiàng)，會(huì)輸出 JSON 對(duì)象。這個(gè)輸出結(jié)果可以被 webpack 的 analyse 工具，或者 chrisbateman 的 webpack-visualizer，再或者 th0r 的 webpack-bundle-analyzer 所識(shí)別。analyse 工具會(huì)接收 JSON，并以圖形的形式展示所有構(gòu)建的細(xì)節(jié)。

Environment 選項(xiàng)

當(dāng) webpack 配置導(dǎo)出為函數(shù)時(shí)，會(huì)接收到一個(gè) "environment" 的參數(shù)。

env

npx webpack --env production    # env.production = true

--env 參數(shù)可以接收多個(gè)值：

Invocation	Resulting environment
npx webpack --env prod	{ prod: true }
npx webpack --env prod --env min	{ prod: true, min: true }
npx webpack --env platform=app --env production	{ platform: "app", production: true }
npx webpack --env foo=bar=app	{ foo: "bar=app"}
npx webpack --env app.platform="staging" --env app.name="test"	{ app: { platform: "staging", name: "test" }

除了上面所說(shuō)的自定義 env 變量，在你的 webpack 配置中也使用了一些 env 內(nèi)置變量：

變量名	描述
WEBPACK_SERVE	如果使用了 serve|server|s，則為 true。
WEBPACK_BUILD	如果使用了 build|bundle|b，則為 true。
WEBPACK_WATCH	如果使用了 --watch|watch|w，則為 true。

請(qǐng)注意你不能在 bundle 代碼中使用這些內(nèi)置環(huán)境變量。

module.exports = (env, argv) => {
  return {
    mode: env.WEBPACK_SERVE ? 'development' : 'production',
  };
};

node-env

你可以使用 --node-env 選項(xiàng)來(lái)設(shè)置 process.env.NODE_ENV:

npx webpack --node-env production   # process.env.NODE_ENV = 'production'

配置選項(xiàng)

參數(shù)	說(shuō)明	輸入類型	默認(rèn)值
--config	配置文件的路徑	string[]	默認(rèn)配置
--config-name	要使用的配置名	string[]
--env	當(dāng)配置文件為函數(shù)時(shí)，environment 將作為參數(shù)傳遞給配置	string[]

分析 Bundle

你可以使用 webpack-bundle-analyzer 插件來(lái)分析你 webpack 輸出的 bundle。你還可以通過(guò) CLI 的 --analyze flag 調(diào)用它

npx webpack --analyze

Progress

如需查看 webpack 的編譯進(jìn)度，你可以使用 --progress flag。

npx webpack --progress

如需收集編譯過(guò)程中每一步的 profile 數(shù)據(jù)，你可以將 profile 作為值傳遞給 --progress flag。

npx webpack --progress=profile

將 CLI 參數(shù)傳遞給 Node.js

將參數(shù)直接傳遞給 Node.js 進(jìn)程，你可以使用 NODE_OPTIONS 選項(xiàng)。

例如，將 Node.js 進(jìn)程的內(nèi)存限制增加到 4 GB。

NODE_OPTIONS="--max-old-space-size=4096" webpack

此外，你也可以將多個(gè)選項(xiàng)傳遞給 Node.js 進(jìn)程。

NODE_OPTIONS="--max-old-space-size=4096 -r /path/to/preload/file.js" webpack

退出代碼及其含義

退出代碼	描述
0	成功
1	webpack Error
2	配置/選項(xiàng)問(wèn)題，或者內(nèi)部錯(cuò)誤

CLI 環(huán)境變量

環(huán)境變量	描述
WEBPACK_CLI_SKIP_IMPORT_LOCAL	設(shè)置為 true 時(shí)將不會(huì)使用 webpack-cli 本地實(shí)例。
WEBPACK_CLI_FORCE_LOAD_ESM_CONFIG	設(shè)置為 true 則強(qiáng)制加載 ESM 配置。
WEBPACK_PACKAGE	在 CLI 中使用自定義 webpack 版本。
WEBPACK_DEV_SERVER_PACKAGE	在 CLI 中使用自定義 webpack-dev-server 版本。
WEBPACK_CLI_HELP_WIDTH	用于幫助輸出的自定義寬度。

WEBPACK_CLI_FORCE_LOAD_ESM_CONFIG=true npx webpack --config ./webpack.config.esm

WEBPACK_PACKAGE

在 CLI 中使用自定義 webpack 版本。在你的 package.json 中配置以下內(nèi)容：

{
  "webpack": "^4.0.0",
  "webpack-5": "npm:webpack@^5.32.0",
  "webpack-cli": "^4.5.0"
}

使用 webpack v4.0.0：

npx webpack

使用 webpack v5.32.0：

WEBPACK_PACKAGE=webpack-5 npx webpack

Troubleshooting

當(dāng)使用 TypeScript 的原生 ESM（即在 package.json 中設(shè)置 type: "module"）時(shí)，可能會(huì)遇到此錯(cuò)誤：

TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for ./webpack.config.ts

webpack-cli 支持 CommonJS 和 ESM 格式的配置，首先嘗試使用 require() 加載配置，如果出現(xiàn)錯(cuò)誤代碼 'ERR_REQUIRE_ESM'（用于這種情況的特殊代碼），則會(huì)嘗試使用 import() 加載配置。但是，如果沒(méi)有啟用 loader hooks（TypeStrong/ts-node#1007 中有描述），則 import() 方法將無(wú)法使用 ts-node。

要解決上述錯(cuò)誤，請(qǐng)使用以下命令：

NODE_OPTIONS="--loader ts-node/esm" npx webpack --entry ./src/index.js --mode production

有關(guān)在 TypeScript 中編寫(xiě) webpack 配置的更多信息，請(qǐng)參見(jiàn)我們的文檔。

Further Reading

• 分析構(gòu)建的統(tǒng)計(jì)數(shù)據(jù)
• 檢查 webpack 包的三種簡(jiǎn)單方法
• 使用 webpack 優(yōu)化應(yīng)用程序包
• 使用 webpack 和 source-map-explorer 分析并減小 client-side 包