CLI 命令行接口

webpackjsorg-mainAPI 参考

命令行接口

为了正确使用并更轻松地分发此配置，webpack 可以使用 webpack.config.js 进行配置。发送到 CLI 的任何参数都将映射到配置文件中的相应参数。

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

W> webpack-cli v7.0.0+ 需要 node >= v20.9.0、webpack >= v5.101.0 和 webpack-dev-server >= v5.0.0。

W> 如果你想使用 npx 运行 webpack，请确保已安装 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]`	输出关于你的系统信息。
`serve`	`serve\|server\|s [options]`	运行 `webpack-dev-server`。
`version`	`version\|v [commands...]`	输出 'webpack'、'webpack-cli'、'webpack-dev-server' 以及其他包的版本号。
`watch`	`watch\|w [entries...] [options]`	运行 webpack 并监听文件变化。

Build

运行 webpack（默认命令，可以省略）。

bash 复制代码

npx webpack build [options]

示例

bash 复制代码

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

Init

用于使用 create-webpack-app 初始化一个新的 webpack 项目。

bash 复制代码

npx create-webpack-app [generation-path] [options]

示例

bash 复制代码

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

等同于：

bash 复制代码

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

生成路径

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

选项

-t, --template

string = 'default'

要生成的模板名称。

-f, --force

boolean

无需提问即可生成项目。启用时，每个问题将使用默认答案。

支持的模板

--template=default - 带有基本配置的默认模板。
--template=react - 带有 React 配置的模板。
--template=vue - 带有 Vue 配置的模板。
--template=svelte - 带有 Svelte 配置的模板。

Loader

生成一个 loader 脚手架。

bash 复制代码

npx create-webpack-app loader [output-path] [options]

示例

bash 复制代码

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

输出路径

输出目录的路径，例如 ./loader-name。

选项

-t, --template

string = 'default'

模板类型。

Plugin

生成一个 plugin 脚手架。

bash 复制代码

npx create-webpack-app plugin [output-path] [options]

示例

bash 复制代码

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

输出路径

输出目录的路径，例如 ./plugin-name。

选项

-t, --template

string = 'default'

模板类型。

T> 查看 create-webpack-app 的完整文档。

Info

输出关于你系统的信息。

bash 复制代码

npx webpack info [options]

示例

bash 复制代码

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

info 的选项

-a, --additional-package

string

将额外的包添加到输出中。

示例

bash 复制代码

npx webpack info --additional-package postcss

-o, --output

string : 'json' | 'markdown'

以指定格式获取输出。

示例

bash 复制代码

npx webpack info --output markdown

Configtest

校验 webpack 配置。

bash 复制代码

npx webpack configtest [config-path]

示例

bash 复制代码

npx webpack configtest ./webpack.config.js

配置路径

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

Serve

运行 webpack dev server。

bash 复制代码

npx webpack serve [options]

示例

bash 复制代码

npx webpack serve --static --open

T> 查看 webpack serve 命令的完整选项列表以及 webpack-dev-server 的相关文档。

Watch

运行 webpack 并监听文件变化。

bash 复制代码

npx webpack watch [options]

示例

bash 复制代码

npx webpack watch --mode development

标志

默认情况下，webpack 自带以下标志：

标志 / 别名	类型	描述
`--entry`	string[]	应用程序的入口点，例如 `./src/main.js`
`--config, -c`	string[]	提供 webpack 配置文件的路径，例如 `./webpack.config.js`
`--config-name`	string[]	要使用的配置名称
`--name`	string	配置的名称。用于加载多个配置时
`--color`	boolean	在控制台上启用颜色
`--merge, -m`	boolean	使用 `webpack-merge` 合并两个或多个配置
`--env`	string[]	传递给配置（当配置为函数时）的环境变量
`--config-node-env`	string	将 `process.env.NODE_ENV` 设置为指定值
`--progress`	boolean, string	在构建期间打印编译进度
`--help`	boolean	输出支持的标志和命令列表
`--output-path, -o`	string	webpack 生成文件的输出位置，例如 `./dist`
`--target, -t`	string[]	设置构建目标
`--watch, -w`	boolean	监听文件变化
`--watch-options-stdin`	boolean	当 stdin 流结束时停止监听
`--devtool, -d`	string	控制是否以及如何生成 source map。
`--json, -j`	boolean, string	将结果以 JSON 格式打印或存储到文件中
`--mode`	string	定义传递给 webpack 的模式
`--version, -v`	boolean	获取当前版本
`--stats`	boolean, string	指示 webpack 如何处理 stats
`--disable-interpret`	boolean	禁用 interpret 来加载配置文件。
`--fail-on-warnings`	boolean	当 webpack 出现警告时，以非零退出码停止 webpack-cli 进程
`--analyze`	boolean	调用 `webpack-bundle-analyzer` 插件以获取 bundle 信息
`--extends, -e`	string[]	扩展现有的配置

否定标志

标志	描述
`--no-color`	在控制台上禁用任何颜色
`--no-hot`	如果你已通过配置启用了热重载，则禁用它
`--no-stats`	禁用 webpack 发出的任何编译统计信息
`--no-watch`	不要监听文件变化
`--no-devtool`	不要生成 source map
`--no-watch-options-stdin`	当 stdin 流结束时不要停止监听

核心标志

从 CLI v4 和 webpack v5 开始，CLI 从 webpack 核心导入整个配置模式，以允许从命令行调整几乎所有的配置选项。

以下是 webpack v5 配合 CLI v4 支持的所有核心标志列表 - 链接

例如，如果你想在项目中启用性能提示，你可以在配置中使用此选项，使用核心标志，你可以这样做：

bash 复制代码

npx webpack --performance-hints warning

用法

使用配置文件

bash 复制代码

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

有关配置文件中的选项，请参阅配置。

不使用配置文件

bash 复制代码

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

示例

bash 复制代码

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

entry

一个文件名或一组命名文件名，作为构建项目的入口点。你可以传入多个入口（每个入口在启动时加载）。
以下是通过 CLI 指定入口文件的多种方式：

bash 复制代码

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

bash 复制代码

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

bash 复制代码

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

bash 复制代码

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

W> 必须使用 --entry-reset 选项来替换现有的 entry 选项，否则 --entry 选项会将另一个入口添加到现有条目中。

T> 使用 webpack [command] --entry-reset [entries...] [option] 语法，因为某些选项可以接受多个值，所以 webpack --target node ./entry.js 表示 target: ['node', './entry.js']。

output-path

打包文件保存的路径。它将映射到配置选项 output.path。

示例

如果你的项目结构如下：

bash 复制代码

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

bash 复制代码

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

这将使用 index.js 作为入口来打包你的源代码，输出 bundle 文件的路径为 dist。

bash 复制代码

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

bash 复制代码

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

这将把两个文件作为单独的入口点来生成 bundle。

bash 复制代码

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.config.js > .webpack/webpack.config.js > .webpack/webpackfile.js 的顺序查找

text 复制代码

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

每个基本名称都会根据支持的扩展名进行解析 —— JavaScript 和 TypeScript 变体（.js、.mjs、.cjs、.ts、.cts、.mts）、其他支持的语言如 .coffee，以及自 webpack-cli 7.1.0 起支持的数据格式 .json5、.yaml/.yml 和 .toml。

常见选项

W> 请注意，对于你使用的参数，命令行接口的优先级高于配置文件。例如，如果你向 webpack CLI 传递 --mode="production" 而你的配置文件使用 development，则将使用 production。

help

列出 CLI 上可用的基本命令和标志

webpack help [command] [option] 和 webpack [command] --help 都可用来获取帮助：

bash 复制代码

npx webpack --help

# 或

npx webpack help

列出 CLI 支持的所有命令和标志

bash 复制代码

npx webpack --help=verbose

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

bash 复制代码

npx webpack help --mode

version

输出 'webpack'、'webpack-cli' 和 'webpack-dev-server' 以及其他包的版本号

要检查你正在使用的 webpack 和 webpack-cli 的版本，请运行命令：

bash 复制代码

npx webpack --version

# 或

npx webpack version

这将输出以下结果：

bash 复制代码

webpack 5.31.2
webpack-cli 4.6.0

如果你安装了 webpack-dev-server，它也会输出其版本：

bash 复制代码

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

config

使用配置文件构建源代码

指定一个与默认的 webpack.config.js 不同的配置文件。

bash 复制代码

npx webpack --config example.config.js

config-name

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

考虑以下 webpack.config.js：

js 复制代码

export default [
  {
    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",
  },
];

只运行 second 配置：

bash 复制代码

npx webpack --config-name second

你也可以传递多个值：

bash 复制代码

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

merge

你可以借助 --merge 合并两个或多个不同的 webpack 配置：

bash 复制代码

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

extends

你可以借助 --extends 扩展现有的 webpack 配置：

bash 复制代码

npx webpack --extends ./base.webpack.config.js

更多信息请阅读扩展配置。

json

将 webpack 的结果输出为 JSON

bash 复制代码

npx webpack --json

如果你想将 stats 存储为 JSON 而不是打印它，你可以使用：

bash 复制代码

npx webpack --json stats.json

在其他情况下，webpack 会打印出一组显示 bundle、chunk 和时序细节的 stats。使用此选项，输出可以是一个 JSON 对象。此响应可被 webpack 的分析工具、chrisbateman 的 webpack-visualizer 或 th0r 的 webpack-bundle-analyzer 接受。分析工具将获取 JSON 并以图形形式提供构建的所有细节。

T> 查看 stats 数据 API 以阅读更多关于此处生成的 stats 的信息。

环境选项

当 webpack 配置导出一个函数时，可以向其传递一个“环境”。

env

bash 复制代码

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

--env 参数接受多个值：

调用	产生的环境
`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" }`

T> 如果你想显式地将变量设置为空字符串（""），你可能需要在终端中转义字符，例如 npx webpack --env foo=\"\"。

T> 查看环境变量指南以了解更多用法。

除了上面展示的自定义 env 之外，还有一些内置的 env 可以在你的 webpack 配置中使用：

环境变量	描述
`WEBPACK_SERVE`	如果正在使用 `serve\|server\|s`，则为 `true`。
`WEBPACK_BUILD`	如果正在使用 `build\|bundle\|b`，则为 `true`。
`WEBPACK_WATCH`	如果正在使用 `--watch\|watch\|w`，则为 `true`。

请注意，你不可以在打包后的代码中访问这些内置环境变量。

js 复制代码

export default (env, argv) => ({
  mode: env.WEBPACK_SERVE ? "development" : "production",
});

config-node-env

为你的配置设置 process.env.NODE_ENV：

bash 复制代码

npx webpack --config-node-env production   # process.env.NODE_ENV = 'production' in `webpack.config.js`

当配置中未指定 mode 选项时，你可以使用 --config-node-env 选项来设置 mode。例如，使用 --config-node-env production 会将 process.env.NODE_ENV 和 mode 都设置为 'production'。

如果你的配置导出的是一个函数，--config-node-env 的值会在函数返回后赋值给 mode。这意味着 mode 在函数参数（env 和 argv）中不可用。但是，--config-node-env 的值在函数内部可以通过 argv.nodeEnv 访问，并可以根据需要使用。

js 复制代码

export default (env, argv) => {
  console.log(argv.defineProcessEnvNodeEnv); // 如果使用 --config-node-env production 则为 'production'
  return {
    // 你的配置
  };
};

配置选项

参数	说明	输入类型	默认值
`--config`	配置文件的路径	string[]	默认配置
`--config-name`	要使用的配置名称	string[]
`--env`	传递给配置的环境（当其为函数时）	string[]

分析 Bundle

你也可以使用 webpack-bundle-analyzer 来分析 webpack 生成的输出 bundle。你可以使用 --analyze 标志通过 CLI 调用它。

bash 复制代码

npx webpack --analyze

W> 确保你的项目中已安装 webpack-bundle-analyzer，否则 CLI 会提示你安装它。

进度

要检查任何 webpack 编译的进度，你可以使用 --progress 标志。

bash 复制代码

npx webpack --progress

要为进度步骤收集分析数据，你可以将 profile 作为值传递给 --progress 标志。

bash 复制代码

npx webpack --progress=profile

将 CLI 参数传递给 Node.js

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

例如，要将 Node.js 进程的内存限制提高到 4 GB：

bash 复制代码

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

此外，你可以向 Node.js 进程传递多个选项：

bash 复制代码

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

退出码及其含义

退出码	描述
`0`	成功
`1`	webpack 的错误
`2`	配置/选项问题或内部错误

CLI 环境变量

环境变量	描述
`WEBPACK_CLI_SKIP_IMPORT_LOCAL`	当为 `true` 时，将跳过使用本地的 `webpack-cli` 实例。
`WEBPACK_CLI_FORCE_LOAD_ESM_CONFIG`	当为 `true` 时，将强制加载 ESM 配置。
`WEBPACK_PACKAGE`	在 CLI 中使用自定义的 webpack 版本。
`WEBPACK_DEV_SERVER_PACKAGE`	在 CLI 中使用自定义的 webpack-dev-server 版本。
`WEBPACK_CLI_HELP_WIDTH`	为帮助输出使用自定义宽度。

bash 复制代码

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

WEBPACK_PACKAGE

在 CLI 中使用自定义的 webpack 版本。考虑在你的 package.json 中包含以下内容：

json 复制代码

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

使用 webpack v4.0.0：

bash 复制代码

npx webpack

使用 webpack v5.32.0：

bash 复制代码

WEBPACK_PACKAGE=webpack-5 npx webpack

故障排除

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

如果你在 TypeScript 中使用原生 ESM（即 package.json 中的 type: "module"），可能会遇到此错误。

webpack-cli 支持 CommonJS 和 ESM 格式的配置，它首先尝试使用 import() 加载配置，一旦失败，它会尝试使用 require() 加载配置。
但是，如果没有启用加载器钩子，import() 方法将无法与 ts-node 一起使用（详见 TypeStrong/ts-node#1007）。

要修复上述错误，请使用以下命令：

bash 复制代码

NODE_OPTIONS="--import=data:text/javascript,import { register } from 'node:module'; import { pathToFileURL } from 'node:url'; register('ts-node/esm', pathToFileURL('./'));" npx webpack --entry ./src/index.js --mode production

更多信息，请参阅我们关于用 TypeScript 编写 webpack 配置的文档。

帮助我们改进文档

发现翻译问题或内容错误？请告诉我们。