html-webpack-plugin 插件用法详解与配置指南

作者：脚本小铺时间：2026-10-22 17:46:02浏览：664

本文详细解析 html-webpack-plugin 在 Webpack 项目中的核心用法。内容涵盖安装方式、默认行为机制，以及 template、filename、inject、minify 和 chunks 等关键配置参数的具体作用与示例。通过多入口文件处理、自定义模板及压缩选项的讲解，帮助开发者掌握生成优化 HTML 文件的完整流程。

html-webpack-plugin 概述与安装

html-webpack-plugin 是 Webpack 生态中用于处理 HTML 文件编译的核心插件。若直接将 HTML 文件放置在 ./src 目录下，Webpack 默认不会将其打包至生产环境，因为所有文件的编译均需基于预先配置的配置文件进行。

使用 Webpack 插件通常遵循三个基本步骤：安装依赖、引入模块以及进行配置。

使用 npm 进行安装。


npm install --save-dev html-webpack-plugin

使用 yarn 进行安装。


yarn add html-webpack-plugin --dev

默认行为与入口配置

当未定义 html-webpack-plugin 的入口参数时。


//webpack.config.js 
const path = require('path');
const htmlWebpackPlugin = require('html-webpack-plugin');

module.exports = {
  entry: {
    home: path.resolve(__dirname, './src/app.js')
  },
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].js'
  },
  plugins: [
    new htmlWebpackPlugin()
  ]
}

生成的 HTML 文件路径为：dist/index.html


<!DOCTYPE html>
<html>
 <head>
  <meta charset="UTF-8">
  <title>Webpack App</title>
 </head>
 <body>
 <script type="text/javascript" src="home.js"></script></body>
</html>

以下是最简化的 webpack.config.js 配置示例，其中 html-webpack-plugin 未传递任何参数。根据插件默认原则，当 Entrypoint 未定义时，输出文件默认为 index.html。因此，即使 ./src 目录下存在其他名称的 HTML 文件，它们也不会被打包处理，系统会默认输出一个 index.html 文件。

在 html-webpack-plugin 中，任何自定义参数的设置均会覆盖默认值。

通过简单定义一个入口（在参数对象的 template 字段中设置）来观察效果：

./src/index.html 文件中存在该模板文件。


<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta http-equiv="X-UA-Compatible" content="ie=edge">
  <title>Document</title>
</head>
<body>
  <div id="test">html webpack plugin</div>
</body>
</html>

在 webpack.config.js 中增加 template 字段。


const path = require('path');
const htmlWebpackPlugin = require('html-webpack-plugin');

module.exports = {
  entry: {
    home: path.resolve(__dirname, './src/app.js')
  },
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].js'
  },
  plugins: [
    new htmlWebpackPlugin({
      template: './src/index.html'//只增加了这行
    })
  ]
}

打包结果生成 dist/home.js 和 dist/index.html。其中 HTML 文件内容与 src 目录下创建的原始文件完全一致，这证明自定义入口已生效，并成功覆盖了默认入口行为。


<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta http-equiv="X-UA-Compatible" content="ie=edge">
  <title>Document</title>
</head>
<body>
  <div id="test">html webpack plugin</div>
</body>
</html>

自定义模板与输出文件名

在配置 template: './src/index2.html' 时，template 的值指定了 HTML 文件的入口源，其作用类似于 JS 文件中的 entry 字段。仅设置 template 时，默认输出文件名仍为 index.html，具体输出文件名需通过 filename 字段进行设置。

template 参数指定生成文件所依赖的 HTML 模板，模板类型可支持 html、jade、ejs 等。需要注意的是，若使用自定义模板文件，必须安装对应的 loader 以支持解析。

当配置了 HTML 文件的出口 filename 参数时。


const path = require('path');
const htmlWebpackPlugin = require('html-webpack-plugin');

module.exports = {
  entry: {
    home: path.resolve(__dirname, './src/app.js')
  },
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].js'
  },
  plugins: [
    new htmlWebpackPlugin({
      template: './src/index2.html',
      filename: 'index.output.html'
    })
  ]
}

输出结果为 dist/home.js 和 dist/index.output.html。

与 webpack.config.js 配置文件中 output 属性的 filename 字段类似，htmlWebpackPlugin({}) 的 filename 字段也支持在值中添加文件夹路径以实现文件分类存储。


const path = require('path');
const htmlWebpackPlugin = require('html-webpack-plugin');

module.exports = {
  entry: {
    home: path.resolve(__dirname, './src/app.js')
  },
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].js'
  },
  plugins: [
    new htmlWebpackPlugin({
      template: './src/index2.html',
      filename: './category/index.output.html'
    })
  ]
}

输出结果为 dist/home.js 和 dist/category/index.output.html。

其他常用配置参数

title 字段仅在未定义 template 模板文件时生效，即仅在使用默认输出文件 index.html 时，title 设置才起作用。若指定了 template，其值将被指定模板文件中的 title 覆盖，title 的默认值为 Webpack App。

favicon 配置。

值为 './somepath/favicon.ico'，指定 favicon.ico 图标的路径。

inject 参数有四个可选值：true、body、head、false，用于指定 script 标签在何处（body 或 head）引入生成的 JS 文件。

true 为默认值，script 标签位于 HTML 文件的 body 底部。
body 表示 script 标签位于 HTML 文件的 body 底部。
head 表示 script 标签位于 HTML 文件的 head 中。
false 表示不插入生成的 JS 文件，此选项几乎不被使用。

其中 body 和 head 为字符串类型，需加引号；false 和 true 为 Boolean 类型值。

minify 的值是一个对象，用于设置压缩属性。


plugins: [

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

hash：布尔值，用于生成哈希值以清除缓存。
cache：布尔值，指定文件是否进行缓存。
showErrors：布尔值，将错误信息写入 HTML 页面。
meta：{} 值为对象，用于设置元信息。


meta：{viewport: 'width=device-width, initial-scale=1, shrink-to-fit=no'}

xhtml 配置。

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

多入口文件处理（chunks）

chunks 配置。

chunks 主要用于多入口文件场景。当存在多个入口文件时，编译后会生成多个打包后的 JS 文件，此时 chunks 选项允许选择要引入的特定 JS 文件。


entry: {
  index: path.resolve(__dirname, './src/index.js'),
  devor: path.resolve(__dirname, './src/devor.js'),
  main: path.resolve(__dirname, './src/main.js')
}

plugins: [
  new httpWebpackPlugin({
    chunks: ['index','main']
  })
]

编译后的结果如下所示。


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

若未设置 chunks 选项，默认情况下 HTML 文件会引入所有 entry 中的 JS 文件。

excludeChunks 和 Chunks作用是一样的，值也都是数组形式，对多入口js进行选择

排除掉一些js。


excludeChunks: ['devor.js']
// 等价于上面的

xhtml 配置。

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

以上就是本文的全部内容，希望对大家的学习有所帮助，也希望大家多多支持本站。

作者最新文章

JS压缩后代码报错怎么调试？Source Map使用详解

2026-11-05 09:05:04

JS压缩会破坏代码逻辑吗？兼容性风险与测试建议

2026-11-03 17:13:03

Next.js 与 Vite、Create React App 的优缺点对比

2026-11-03 15:27:33

js文件加载失败或404错误的常见原因与排查

2026-11-03 10:38:55

前端项目打包生成 JS 文件的核心步骤完整记录

2026-10-31 21:04:46