html-webpack-plugin 配置选项详解

html-webpack-plugin 概述

使用过 webpack 的开发者大多接触过 html-webpack-plugin，即便未曾直接使用，也常有所耳闻。在学习 webpack 的过程中，经常能看到类似如下代码的配置示例。

// webpack.config.js
module.exports = {
  entry: path.resolve(__dirname, './app/index.js'),
  output:{
    path: path.resolve(__dirname, './build'),
    filename: 'bundle.js'
  }
  ...
  plugins: [
    new HtmlWebpackPlugin()
  ]
}

随后在终端执行 webpack 命令后

webpack

令人惊喜的是，build 文件夹中会自动生成 index.html 和 bundle.js 两个文件，且 index.html 会自动引用由 webpack 生成的 bundle.js。

这一切均归功于 html-webpack-plugin。该插件能自动生成 HTML 文件，并自动引用所需的资源文件（如 CSS、JS 等）。

今年六月，笔者初次接触前端自动化构建，学习 webpack 和 react 时曾简单使用过此插件，但仅涉及常见选项。本文将结合官方文档，全面梳理其所有用法。

基础配置选项

title

顾名思义，该参数用于设置生成 HTML 文件的标题。

filename

此参数用于指定生成的 HTML 文件名，默认为 index.html。

template

通过指定模板文件来生成特定的 HTML 文件。模板类型可以是任意你喜欢的格式，包括 html、jade、ejs、hbs 等。需要注意的是，使用自定义模板时，需提前安装对应的 loader，否则 webpack 无法正确解析。以 jade 为例。

npm install jade-loader --save-dev

// webpack.config.js
...
loaders: {
  ...
  {
    test: /\.jade$/,
    loader: 'jade'
  }
}
plugins: [
  new HtmlWebpackPlugin({
    ...
    jade: 'path/to/yourfile.jade'
  })
]

最终在 build 文件夹内会生成 yourfile.html 和 bundle.js 文件。现在回顾之前提到的 title 属性。

若同时指定 template 和 title 选项，webpack 将优先采用指定模板文件中的 title，即使模板中未显式设置 title。

至于 filename 是否会覆盖，答案是否定的，最终文件名仍以指定的 filename 为准。

资源注入与图标配置

inject

注入选项，包含四个可选值：true、body、head、false。

1. true：默认值，script 标签位于 HTML 文件的 body 底部
2. body：与 true 效果相同
3. head：script 标签位于 head 标签内
4. false：不插入生成的 JS 文件，仅生成一个空的 HTML 文件
5. favicon：用于为生成的 HTML 文件生成 favicon。属性值为 favicon 文件所在的路径名。

// webpack.config.js
...
plugins: [
  new HtmlWebpackPlugin({
    ...
    favicon: 'path/to/yourfile.ico'
  }) 
]

生成的 HTML 标签中将包含如下 link 标签

<link rel="shortcut icon" href="example.ico" rel="external nofollow" >

与 title 和 filename 类似，若在模板文件中指定了 favicon，则该属性将被忽略。

压缩与缓存控制

minify

minify 用于对 HTML 文件进行压缩，其属性值可以是压缩选项对象或 false。默认值为 false，即不压缩生成的 HTML 文件。以下是压缩选项的示例。

html-webpack-plugin 内部集成了 html-minifier，该压缩选项与 html-minify 的压缩选项完全一致， 以下是一个简单的例子。

// webpack.config.js
...
plugins: [
  new HtmlWebpackPlugin({
    ...
    minify: {
      removeAttributeQuotes: true // 移除属性的引号
    }
  })
]

<!-- 原html片段 -->
<div id="example" class="example">test minify</div>

<!-- 生成的html片段 -->
<div id=example class=example>test minify</div>

Hash 与多入口处理

hash

hash 选项用于为生成的 JS 文件添加唯一的 hash 值，该 hash 值对应本次 webpack 编译的 hash。默认值为 false。以下是一个示例。

// webpack.config.js
plugins: [
  new HtmlWebpackPlugin({
    ...
    hash: true
  })
]

<script type=text/javascript src=bundle.js?22b9692e22e7be37b57e></script>

执行 webpack 命令后，你会发现生成的 HTML 文件中 script 标签引用的 JS 文件发生了变化。

bundle.js 文件后跟随的一串 hash 值即为本次 webpack 编译对应的 hash 值。

$ webpack
Hash: 22b9692e22e7be37b57e
Version: webpack 1.13.2

cache

默认值为 true，表示仅在内容发生变化时才生成新文件。

showErrors

showErrors 用于控制 webpack 编译错误信息的显示。若编译出错，webpack 会将错误信息包裹在 pre 标签内。该属性默认值为 true，即显示错误信息。

chunks

chunks 选项主要针对多入口（entry）文件。当存在多个入口文件时，会生成多个编译后的 JS 文件。chunks 选项用于决定引用哪些生成的 JS 文件。

默认情况下，生成的 HTML 文件会引用所有 JS 文件，但也可以指定仅引入特定的文件。

以下是一个小例子。

// webpack.config.js
entry: {
  index: path.resolve(__dirname, './src/index.js'),
  index1: path.resolve(__dirname, './src/index1.js'),
  index2: path.resolve(__dirname, './src/index2.js')
}
...
plugins: [
  new HtmlWebpackPlugin({
    ...
    chunks: ['index','index2']
  })
]

执行 webpack 命令后，生成的 index.html 文件中仅引用了 index.js 和 index2.js

...
<script type=text/javascript src=index.js></script>
<script type=text/javascript src=index2.js></script>

若未指定 chunks 选项，默认会引用所有文件。

excludeChunks

理解 chunks 后，excludeChunks 选项便易于掌握，它与 chunks 作用相反，用于排除某些 JS 文件。例如，上述例子等价于以下配置

...
excludeChunks: ['index1.js']

脚本排序与 XHTML 兼容

chunksSortMode

此选项决定 script 标签的引用顺序。默认包含四个选项：'none'、'auto'、'dependency'、'{function}'。

1. 'dependency'：根据文件依赖关系排序。
2. 'auto'：默认值，插件内置的排序方式，具体顺序尚不明确...
3. 'none'：无序？尚不明确...
4. {function}：提供自定义函数？但函数参数为何？尚不明确...

若有使用过此选项或了解其具体含义的开发者，欢迎告知...

xhtml

布尔值，默认值为 false。若设为 true，则以兼容 XHTML 的模式引用文件。

总结

以上即为传入 new HtmlWebpackPlugin() 的所有配置选项。全面了解各选项含义后，可在项目构建时更灵活地使用该插件。希望对大家的学习有所帮助，也希望大家多多支持本站。