赞助 webpack,同时从官方商店购买衣服 所有收益将转到我们的 open collective

命令行接口

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

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

使用配置文件的用法

webpack [--config webpack.config.js]

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

不使用配置文件的用法

webpack <entry> [<entry>] -o <output>

<entry>

一个文件名或一组被命名的文件名,作为构建项目的入口起点。你可以传递多个入口(每个入口在启动时加载)。如果传递一个形式为 <name> = <request> 的键值对,则可以创建一个额外的入口起点。它将被映射到配置选项(configuration option)的 entry 属性。

<output>

要保存的 bundled 文件的路径和文件名。它将映射到配置选项 output.pathoutput.filename

示例

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

.
├── dist
├── index.html
└── src
    ├── index.js
    ├── index2.js
    └── others.js
webpack src/index.js -o dist/bundle.js

打包源码,入口为 index.js,并且输出文件的路径为 dist,文件名为 bundle.js

    | Asset     | Size    | Chunks      | Chunk Names |
    |-----------|---------|-------------|-------------|
    | bundle.js | 1.54 kB | 0 [emitted] | index       |
    [0] ./src/index.js 51 bytes {0} [built]
    [1] ./src/others.js 29 bytes {0} [built]
webpack index=./src/index.js entry2=./src/index2.js dist/bundle.js

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

    | Asset     | Size    | Chunks        | Chunk Names   |
    |-----------|---------|---------------|---------------|
    | bundle.js | 1.55 kB | 0,1 [emitted] | index, entry2 |
    [0] ./src/index.js 51 bytes {0} [built]
    [0] ./src/index2.js 54 bytes {1} [built]
    [1] ./src/others.js 29 bytes {0} {1} [built]

常用配置

注意,命令行接口(Command Line Interface)参数的优先级,高于配置文件参数。例如,如果将 --mode="production" 传入 webpack CLI,而配置文件使用的是 development,最终会使用 production

列出命令行所有可用的配置选项

webpack --help
webpack -h

使用配置文件进行构建

指定其它的配置文件。配置文件默认为 webpack.config.js,如果你想使用其它配置文件,可以加入这个参数。

webpack --config example.config.js

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

webpack --json
webpack --json > stats.json

在其他每个情况下,webpack 会打印一组统计信息,用于显示 bundle, chunk 和用时等详细信息。使用此选项,输出可以是 JSON 对象。此输出文件(response)可被 webpack 的分析工具,或 chrisbateman 的 webpack 可视化工具,或 th0r 的 webpack bundle 分析工具接收后进行分析。分析工具将接收 JSON 并以图形形式提供构建的所有细节。

环境选项

当 webpack 配置对象导出为一个函数时,可以向起传入一个"环境对象(environment)"。

webpack --env.production    # 设置 env.production == true
webpack --env.platform=web  # 设置 env.platform == "web"

--env 参数具有多种语法 accepts various syntaxes:

Invocation
Resulting environment
Invocation
webpack --env prod
Resulting environment
"prod"
Invocation
webpack --env.prod
Resulting environment
{ prod: true }
Invocation
webpack --env.prod=1
Resulting environment
{ prod: 1 }
Invocation
webpack --env.prod=foo
Resulting environment
{ prod: "foo" }
Invocation
webpack --env.prod --env.min
Resulting environment
{ prod: true, min: true }
Invocation
webpack --env.prod --env min
Resulting environment
[{ prod: true }, "min"]
Invocation
webpack --env.prod=foo --env.prod=bar
Resulting environment
{prod: [ "foo", "bar" ]}
See the environment variables guide for more information on its usage.

配置选项

参数
说明
输入类型
默认值
参数
--config
说明
配置文件的路径
输入类型
string
默认值
webpack.config.js 或 webpackfile.js
参数
--config-register, -r
说明
在 webpack 配置文件加载前先预加载一个或多个模块
输入类型
array
默认值
参数
--config-name
说明
要使用的配置名称
输入类型
string
默认值
参数
--env
说明
当配置文件是一个函数时,会将环境变量传给这个函数
输入类型
参数
--mode
说明
用到的模式,"development" 或 "production" 之中的一个
输入类型
string
默认值

输出配置

通过以下这些配置,你可以调整构建流程的某些输出参数。

参数
说明
输入类型
默认值
参数
--output-chunk-filename
说明
输出的附带 chunk 的文件名
输入类型
string
默认值
含有 [id] 的文件名,而不是 [name] 或者 [id] 作为前缀
参数
--output-filename
说明
打包文件的文件名
输入类型
string
默认值
[name].js
参数
--output-jsonp-function
说明
加载 chunk 时使用的 JSONP 函数名
输入类型
string
默认值
webpackJsonp
参数
--output-library
说明
以库的形式导出入口文件
输入类型
string
默认值
参数
--output-library-target
说明
以库的形式导出入口文件时,输出的类型
输入类型
string
默认值
var
参数
--output-path
说明
输出的路径(在公共路径的基础上)
输入类型
string
默认值
当前目录
参数
--output-pathinfo
说明
加入一些依赖信息的注解
输入类型
boolean
默认值
false
参数
--output-public-path
说明
The 输出文件时使用的公共路径
输入类型
string
默认值
/
参数
--output-source-map-filename
说明
生成的 SourceMap 的文件名
输入类型
string
默认值
[name].map or [outputFilename].map
参数
--build-delimiter
说明
在构建输出之后,显示的自定义文本
输入类型
string
默认值
默认字符串是 null。你可以提供一个 === Build done === 这样的字符串

示例用法

webpack index=./src/index.js index2=./src/index2.js --output-path='./dist' --output-filename='[name][hash].bundle.js'

| Asset                                | Size    | Chunks      | Chunk Names   |
|--------------------------------------|---------|-------------|---------------|
| index2740fdca26e9348bedbec.bundle.js |  2.6 kB | 0 [emitted] | index2        |
| index740fdca26e9348bedbec.bundle.js  | 2.59 kB | 1 [emitted] | index         |
    [0] ./src/others.js 29 bytes {0} {1} [built]
    [1] ./src/index.js 51 bytes {1} [built]
    [2] ./src/index2.js 54 bytes {0} [built]
webpack.js index=./src/index.js index2=./src/index2.js --output-path='./dist' --output-filename='[name][hash].bundle.js' --devtool source-map --output-source-map-filename='[name]123.map'

| Asset                                | Size    | Chunks      | Chunk Names   |
|--------------------------------------|---------|-------------|---------------|
| index2740fdca26e9348bedbec.bundle.js | 2.76 kB | 0 [emitted] | index2        |
|  index740fdca26e9348bedbec.bundle.js | 2.74 kB | 1 [emitted] | index         |
|                        index2123.map | 2.95 kB | 0 [emitted] | index2        |
|                         index123.map | 2.95 kB | 1 [emitted] | index         |
    [0] ./src/others.js 29 bytes {0} {1} [built]
    [1] ./src/index.js 51 bytes {1} [built]
    [2] ./src/index2.js 54 bytes {0} [built]

Debug 配置

以下这些配置可以帮助你在 Webpack 编译过程中更好地 debug。

参数
说明
输入类型
默认值
参数
--debug
说明
把 loader 设置为 debug 模式
输入类型
boolean
默认值
false
参数
--devtool
说明
为打包好的资源定义 [source map 的类型]
输入类型
string
默认值
-
参数
--progress
说明
打印出编译进度的百分比值
输入类型
boolean
默认值
false
参数
--display-error-details
说明
展示错误细节
输入类型
boolean
默认值
false

模块配置

这些配置可以用于绑定 Webpack 允许的模块

参数
说明
用法
参数
--module-bind
说明
为 loader 绑定一个文件扩展
用法
--module-bind js=babel-loader
参数
--module-bind-post
说明
为 post loader 绑定一个文件扩展
用法
参数
--module-bind-pre
说明
为 pre loader 绑定一个文件扩展
用法

Watch 选项

这些配置可以用于观察依赖文件的变化,一旦有变化,则可以重新执行构建流程。

参数
说明
参数
--watch, -w
说明
观察文件系统的变化
参数
--watch-aggregate-timeout
说明
指定一个毫秒数,在这个时间内,文件若发送了多次变化,会被合并
参数
--watch-poll
说明
轮询观察文件变化的时间间隔(同时会打开轮询机制)
参数
--watch-stdin, --stdin
说明
当 stdin 关闭时,退出进程

性能优化配置

在生产环境的构建时,这些配置可以用于调整的一些性能相关的配置。

参数
说明
使用的插件
参数
--optimize-max-chunks
说明
限制 chunk 的数量
使用的插件
参数
--optimize-min-chunk-size
说明
限制 chunk 的最小体积
使用的插件
参数
--optimize-minimize
说明
压缩混淆 javascript,并且把 loader 设置为 minimizing
使用的插件

Resolve 配置

这些配置可以用于设置 webpack resolver 时使用的别名(alias)和扩展名(extension)。

参数
说明
示例
参数
--resolve-alias
说明
指定模块的别名
示例
--resolve-alias jquery-plugin=jquery.plugin
参数
--resolve-extensions
说明
指定需要被处理的文件的扩展名
示例
--resolve-extensions .es6 .js .ts
参数
--resolve-loader-alias
说明
最小化 JavaScript,并且将 loader 切换到最简
示例

统计数据配置

以下选项用于配置 Webpack 在控制台输出的统计数据,以及这些数据的样式。

参数
说明
Type
参数
--color, --colors
说明
强制在控制台开启颜色 [默认:仅对 TTY 输出启用]
Type
boolean
参数
--no-color, --no-colors
说明
强制在控制台关闭颜色
Type
boolean
参数
--display
说明
选择显示预设(verbose - 繁琐, detailed - 细节, normal - 正常, minimal - 最小, errors-only - 仅错误, none - 无; 从 webpack 3.0.0 开始)
Type
string
参数
--display-cached
说明
在输出中显示缓存的模块
Type
boolean
参数
--display-cached-assets
说明
在输出中显示缓存的 assets
Type
boolean
参数
--display-chunks
说明
在输出中显示 chunks
Type
boolean
参数
--display-depth
说明
显示从入口起点到每个模块的距离
Type
boolean
参数
--display-entrypoints
说明
在输出中显示入口文件
Type
boolean
参数
--display-error-details
说明
显示详细的错误信息
Type
boolean
参数
--display-exclude
说明
在输出中显示被排除的文件
Type
boolean
参数
--display-max-modules
说明
设置输出中可见模块的最大数量
Type
number
参数
--display-modules
说明
在输出中显示所有模块,包括被排除的模块
Type
boolean
参数
--display-optimization-bailout
说明
作用域提升回退触发器(Scope hoisting fallback trigger)(从 webpack 3.0.0 开始)
Type
boolean
参数
--display-origins
说明
在输出中显示最初的 chunk
Type
boolean
参数
--display-provided-exports
说明
显示有关从模块导出的信息
Type
boolean
参数
--display-reasons
说明
显示模块包含在输出中的原因
Type
boolean
参数
--display-used-exports
说明
显示模块中被使用的接口(Tree Shaking)
Type
boolean
参数
--hide-modules
说明
隐藏关于模块的信息
Type
boolean
参数
--sort-assets-by
说明
对 assets 列表以某种属性排序
Type
string
参数
--sort-chunks-by
说明
对 chunks 列表以某种属性排序
Type
string
参数
--sort-modules-by
说明
对模块列表以某种属性排序
Type
string
参数
--verbose
说明
显示更多信息
Type
boolean

高级配置

参数
说明
用法
参数
--bail
说明
一旦发生错误,立即终止
用法
参数
--cache
说明
开启缓存 [watch 时会默认打开]
用法
--cache=false
参数
--define
说明
定义 bundle 中的任意自由变量,查看 shimming
用法
--define process.env.NODE_ENV="'development'"
参数
--hot
说明
用法
--hot=true
参数
--labeled-modules
说明
开启模块标签 [使用 LabeledModulesPlugin]
用法
参数
--plugin
说明
加载某个插件
用法
参数
--prefetch
说明
预加载某个文件
用法
--prefetch=./files.js
参数
--provide
说明
在所有模块中将这些模块提供为自由变量,查看 shimming
用法
--provide jQuery=jquery
参数
--records-input-path
说明
记录文件的路径(读取)
用法
参数
--records-output-path
说明
记录文件的路径(写入)
用法
参数
--records-path
说明
记录文件的路径
用法
参数
--target
说明
目标的执行环境
用法
--target='node'

简写

简写
含义
简写
-d
含义
--debug --devtool cheap-module-eval-source-map --output-pathinfo
简写
-p
含义
--optimize-minimize --define process.env.NODE_ENV="production", see building for production

Profiling

--profile 选项捕获编译时每个步骤的时间信息,并且将这些信息包含在输出中。

webpack --profile

⋮
[0] ./src/index.js 90 bytes {0} [built]
    factory:22ms building:16ms = 38ms

For each module, the following details are included in the output as applicable:

  • factory: time to collect module metadata (e.g. resolving the filename)
  • building: time to build the module (e.g. loaders and parsing)
  • dependencies: time to identify and connect the module’s dependencies

Paired with --progress, --profile gives you an in depth idea of which step in the compilation is taking how long. This can help you optimise your build in a more informed manner.

webpack --progress --profile

30ms building modules
1ms sealing
1ms optimizing
0ms basic module optimization
1ms module optimization
1ms advanced module optimization
0ms basic chunk optimization
0ms chunk optimization
1ms advanced chunk optimization
0ms module and chunk tree optimization
1ms module reviving
0ms module order optimization
1ms module id optimization
1ms chunk reviving
0ms chunk order optimization
1ms chunk id optimization
10ms hashing
0ms module assets processing
13ms chunk assets processing
1ms additional chunk assets processing
0ms recording
0ms additional asset processing
26ms chunk asset optimization
1ms asset optimization
6ms emitting
⋮

进一步阅读


贡献人员