Webpack：命令行接口（CLI）

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

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

命令

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

Build

运行 webpack（默认命令，可用输出文件）。

npx webpack build [options]

示例

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

Init

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

npx webpack init [generation-path] [options]

示例

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

生成路径

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

配置

-t, –template

string = default

要生成的模板名称。

-f, –force

boolean

不输入配置项就生成一个项目。该配置启用时所有命令行配置项将使用默认值。

Loader

初始化一个 loader。

npx webpack loader [output-path] [options]

示例

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

Output Path

输出文件夹，例如 ./loader-name。

Options

-t, –template

string = default

模板类型。

Plugin

初始化一个插件。

npx webpack plugin [output-path] [options]

示例

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

Output Path

输出文件夹，例如 ./plugin-name.

Options

-t, –template

string = default

模板类型。

Info

输出你的系统信息。

npx webpack info [options]

示例

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

info 配置项

-a, –additional-package

string

在输出信息中添加额外的包。

example

npx webpack info --additional-package postcss

-o, –output

string : json | markdown

获取指定格式的输出。

示例

npx webpack info --output markdown

Configtest

校验 webpack 配置。

npx webpack configtest [config-path]

示例

npx webpack configtest ./webpack.config.js

Config Path

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

Serve

运行 webpack 开发服务器。

npx webpack serve [options]

示例

npx webpack serve --static --open

Watch

运行 webpack 并且监听文件变化。

npx webpack watch [options]

示例

npx webpack watch --mode development

Flags

默认情况下，webpack 提供了以下 flag：

Negated Flags

核心 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>

示例

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 的版本。

如需检查你正在使用的 webpack 和 webpack-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 参数可以接收多个值：

除了上面所说的自定义 env 变量，在你的 webpack 配置中也使用了一些 env 内置变量：

请注意你不能在 bundle 代码中使用这些内置环境变量。

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

node-env

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

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

配置选项

分析 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

退出代码及其含义

CLI 环境变量

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

Troubleshooting

当使用 TypeScript 的原生 ESM（即在 package.json 中设置 type: “module”）时，可能会遇到此错误：

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

webpack-cli 支持 CommonJS 和 ESM 格式的配置，首先尝试使用 require() 加载配置，如果出现错误代码 ERR_REQUIRE_ESM（用于这种情况的特殊代码），则会尝试使用 import() 加载配置。但是，如果没有启用 loader hooks（TypeStrong/ts-node#1007 中有描述），则 import() 方法将无法使用 ts-node。

要解决上述错误，请使用以下命令：

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

有关在 TypeScript 中编写 webpack 配置的更多信息，请参见我们的文档。

Further Reading

• 分析构建的统计数据
• 检查 webpack 包的三种简单方法
• 使用 webpack 优化应用程序包
• 使用 webpack 和 source-map-explorer 分析并减小 client-side 包