命令行接口(CLI)

为了更合适且方便地使用配置,可以在 webpack.config.js 中对 webpack 进行配置。CLI 中传入的任何参数会在配置文件中映射为对应的参数。

如果你还没有安装过 webpack 和 CLI,请先阅读 安装指南

命令

webpack-cli 提供了许多命令来使 webpack 的工作变得简单。默认情况下,webpack 提供了以下命令:

命令 使用 描述
build build|bundle|b [entries...] [options] 运行 webpack(默认命令,可以被省略)。
configtest configtest|t [config-path] 校验 webpack 配置。
help help|h [command] [option] 展示所有命令和选项的帮助。
info info|i [options] 输出有关系统的信息。
init init|c [scaffold...] [options] 初始化一个新的 webpack 配置。
loader loader|l [output-path] 生成一个 loader 仓库。
plugin plugin|p [output-path] 生成一个 plugin 仓库。
serve serve|s [options] 运行 webpack-dev-server.
version version|v [commands...] 输出 webpackwebpack-cli 以及 webpack-dev-server 的版本信息。
watch watch|w [entries...] [options] 运行 webpack 并监听文件变化。

Init

用于初始化一个新的 webpack 项目。

npx webpack init [generation-path] [options]

example

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

生成路径

生成配置的位置。默认为 process.cwd()

配置

--template

string = 'default'

要生成的模板名称。

--force

boolean

生成项目时不启用选项模式。当为 true 时,所有命令行选项使用默认值。

Info

输出你的系统信息。

npx webpack info [options]

示例

npx webpack info --output=json

info 配置项

--output

string : 'json' | 'markdown'

获取指定格式的输出。

Configtest

校验 webpack 配置。

npx webpack configtest [config-path]

示例

npx webpack configtest ./webpack.config.js

Config Path {configpath}

你的 webpack 配置文件路径。默认为 ./webpack.config.js

Flags

默认情况下,webpack 提供了以下 flag:

Flag / 别名 类型 描述
--entry string[] 应用程序的入口文件,例如 ./src/main.js
--config, -c string[] 提供 webpack 配置文件的路径,例如 ./webpack.config.js
--config-name string[] 要使用的配置名
--name string 配置名称,在加载多个配置时使用
--color boolean 启用控制台颜色
--merge, -m boolean 使用 webpack-merge 合并两个配置文件,例如 -c ./webpack.config.js -c ./webpack.test.config.js
--env string[] 当它是一个函数时,传递给配置的环境变量
--progress boolean, string 在构建过程中打印编译进度
--help boolean 输出所有支持的 flag 和命令
--output-path, -o string webpack 生成文件的输出位置,例如 ./dist
--target, -t string[] 设置要构建的 target
--watch, -w boolean 监听文件变化
--watch-options-stdin boolean stdin stream 结束时,停止监听
--hot, -h boolean 启用 HMR
--devtool, -d string 控制是否生成 source map,以及如何生成
--prefetch string 预先发生请求
--json, -j boolean, string 将结果打印成 JSON 格式或存储在文件中
--mode string 定义 webpack 所需的 mode
--version, -v boolean 获取当前 cli 版本
--stats boolean, string 它告诉 webpack 如何处理 stats
--analyze boolean 它调用 webpack-bundle-analyzer 插件来获取 bundle 信息

Negated Flags

Flag 描述
--no-color 禁用控制台颜色
--no-hot 如果你通过配置启用了 HMR,则禁用它
--no-stats 禁用任何由 webpack emit 出来的 stats
--no-watch 禁用文件变更的监听
--no-devtool 禁止生成 source maps

核心 Flags

从 CLI v4 和 webpack v5 开始,CLI 将采用从 webpack 的 core 中导入整个配置的模式,允许 CLI 调整几乎所有配置项。

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

例如,如果你想在项目中启用性能提示,你需在配置中使用选项,而如果使用核心 flag,你可以这样做:

npx webpack --performance-hints warning

用法

使用配置文件

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

配置文件中的相关选项,请参阅配置

不使用配置文件

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

example

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

entry

构建项目时入口可以配置一个文件名或一组被命名过的文件名。你可以传递多个入口(每个入口在启动时加载)。 如下是通过 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

用于存储构建后的文件路径。它将映射到配置选项 output.path

示例

假设你的项目结构像下面这样:

.
├── dist
├── index.html
└── src
    ├── index.js
    ├── index2.js
    └── others.js
npx webpack ./src/index.js --output-path dist

这将对源码进行打包,其入口为 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/

以多个入口的方式打包文件

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

默认配置

CLI 会在你的项目路径中寻找默认配置,以下是 CLI 采集到的配置文件。

此处按顺序递增进行优先级查询:

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

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

通用配置

help

列出命令行可用的基础命令和 flag

通过 webpack help [command] [option] 以及 webpack [command] --help 均可获得帮助信息:

npx webpack --help

# or

npx webpack help

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

npx webpack --help=verbose

查看特定命令或选项的帮助

npx webpack help --mode

version

显示已安装的 package 以及子 package 的版本

如需检查你正在使用的 webpackwebpack-cli 的版本,只需运行如下命令:

npx webpack --version

# or

npx webpack version

运行结果如下:

webpack 5.31.2
webpack-cli 4.6.0

若已安装 webpack-dev-server,其版本信息会一并输出:

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

如需检查 webpack-cli 子包的版本(如 @webpack-cli/info),只需运行如下命令:

npx webpack info --version

运行结果如下:

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

config

使用配置文件进行构建

配置文件默认为 webpack.config.js,还可以指定其它的配置文件。

npx webpack --config example.config.js

config-name

如果你的配置文件导出了多个配置,你可以使用 --config-name 来指定要运行的配置。

如果你的 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',
  },
];

并且只想运行第二个配置项:

npx webpack --config-name second

你也可以传递多个值来实现:

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

merge

你可以通过 --merge 选项来合并两个或多个不同的 webpack 配置:

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

json

以 JSON 格式输出 webpack 的运行结果

npx webpack --json

如果你想把 stats 数据存储为 JSON 而非输出,你可以使用:

npx webpack --json stats.json

在其他情况下,webpack 会打印出 bundle、chunk 以及 timing 细节的 stats 信息。使用此选项,会输出 JSON 对象。这个输出结果可以被 webpack 的 analyse 工具,或者 chrisbateman 的 webpack-visualizer,再或者 th0r 的 webpack-bundle-analyzer 所识别。analyse 工具会接收 JSON,并以图形的形式展示所有构建的细节。

Environment 选项

当 webpack 配置导出为函数时,会接收到一个 "environment" 的参数。

env

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

--env 参数可以接收多个值:

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" }

node-env

你可以使用 --node-env 选项来设置 process.env.NODE_ENV:

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

配置选项

参数 说明 输入类型 默认值
--config 配置文件的路径 string[] 默认配置
--config-name 要使用的配置名 string[]
--env 当配置文件为函数时,environment 将作为参数传递给配置 string[]

分析 Bundle

你可以使用 webpack-bundle-analyzer 插件来分析你 webpack 输出的 bundle。你还可以通过 CLI 的 --analyze flag 调用它

npx webpack --analyze

Progress

如需查看 webpack 的编译进度,你可以使用 --progress flag。

npx webpack --progress

如需收集编译过程中每一步的 profile 数据,你可以将 profile 作为值传递给 --progress flag。

npx webpack --progress=profile

将 CLI 参数传递给 Node.js

将参数直接传递给 Node.js 进程,你可以使用 NODE_OPTIONS 选项。

例如,将 Node.js 进程的内存限制增加到 4 GB。

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

此外,你也可以将多个选项传递给 Node.js 进程。

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

退出代码及其含义

退出代码 描述
0 成功
1 webpack Error
2 配置/选项问题,或者内部错误

CLI 环境变量

环境变量 描述
WEBPACK_CLI_SKIP_IMPORT_LOCAL 设置为 true 时将不会使用 webpack-cli 本地实例。
WEBPACK_CLI_FORCE_LOAD_ESM_CONFIG 设置为 true 则强制加载 ESM 配置。
WEBPACK_PACKAGE 在 CLI 中使用自定义 webpack 版本。
WEBPACK_CLI_FORCE_LOAD_ESM_CONFIG=true npx webpack --config ./webpack.config.esm

WEBPACK_PACKAGE

在 CLI 中使用自定义 webpack 版本。在你的 package.json 中配置以下内容:

{
  "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

ENV 环境变量

环境变量 描述
WEBPACK_SERVE 如果使用了 serve|s,则为 true
WEBPACK_BUILD 如果使用了 build|bundle|b,则为 true
WEBPACK_WATCH 如果使用了 --watch|watch|w,则为 true

你可以在你的 webpack 配置中使用上述环境变量:

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