html-webpack-plugin配置文档：从入门到专家-优快云博客

html-webpack-plugin配置文档：从入门到专家

【免费下载链接】html-webpack-plugin 项目地址: https://gitcode.com/gh_mirrors/htm/html-webpack-plugin

你是否还在为Webpack构建后的HTML文件引用资源而烦恼？是否想知道如何轻松定制HTML输出、添加favicon或实现多页面应用？本文将系统讲解html-webpack-plugin的配置方法，从基础安装到高级技巧，让你彻底掌握这个Webpack生态中最常用的插件。读完本文，你将能够：配置自定义模板、控制资源注入位置、生成多页面应用、优化生产环境输出。

安装与基本使用

html-webpack-plugin是一个Webpack插件（Plugin），用于简化创建HTML文件以服务Webpack打包后的资源。它特别适用于文件名包含哈希值的场景，能自动更新HTML中的资源引用。

安装命令

根据Webpack版本选择对应的安装命令：

Webpack 5

npm i --save-dev html-webpack-plugin

Webpack 4

npm i --save-dev html-webpack-plugin@4

零配置启动

最简单的用法只需在Webpack配置中添加插件实例：

webpack.config.js

const HtmlWebpackPlugin = require("html-webpack-plugin");

module.exports = {
  entry: "index.js",
  output: {
    path: __dirname + "/dist",
    filename: "index_bundle.js",
  },
  plugins: [new HtmlWebpackPlugin()],
};

上述配置会在dist目录下生成index.html，并自动注入打包后的JS文件。默认生成的HTML结构如下：

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Webpack App</title>
    <script defer src="index_bundle.js"></script>
  </head>
  <body></body>
</html>

完整基础示例可参考examples/default/webpack.config.js。

核心配置选项

html-webpack-plugin提供了丰富的配置选项，以下是常用参数说明：

名称	类型	默认值	描述
`title`	`String`	`Webpack App`	生成HTML文档的标题
`filename`	`String\\|Function`	`'index.html'`	输出HTML文件名，可指定子目录
`template`	`String`	`''`	模板文件路径
`inject`	`Boolean\\|String`	`true`	控制资源注入位置，可选值：`true\\|'head'\\|'body'\\|false`
`favicon`	`String`	`''`	添加favicon图标路径
`minify`	`Boolean\\|Object`	生产环境为`true`	控制HTML压缩
`hash`	`Boolean`	`false`	为资源添加哈希值，用于缓存 busting
`chunks`	`Array.<string>`	`[]`	指定要包含的chunk

常用配置示例

自定义标题和输出文件名

new HtmlWebpackPlugin({
  title: '我的应用',
  filename: 'assets/main.html'
})

控制资源注入位置

new HtmlWebpackPlugin({
  inject: 'body' // 将脚本注入到body底部
})

添加favicon

new HtmlWebpackPlugin({
  favicon: 'src/favicon.ico'
})

模板系统详解

模板系统是html-webpack-plugin最强大的功能之一，允许你完全自定义HTML结构。有三种方式设置模板加载器：

1. 默认lodash模板

未指定任何加载器时，插件会使用内置的fallback ejs loader（基于lodash模板）：

new HtmlWebpackPlugin({
  template: "src/index.html",
})

模板文件中可使用<%= %>语法访问变量：

src/index.html

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title><%= htmlWebpackPlugin.options.title %></title>
  </head>
  <body>
    <h1>Hello <%= process.env.NODE_ENV %></h1>
  </body>
</html>

2. 直接指定加载器

通过内联方式指定模板加载器：

new HtmlWebpackPlugin({
  template: "!!handlebars-loader!src/index.hbs",
})

3. 通过module.rules配置

在Webpack配置中为特定文件类型设置加载器：

module: {
  rules: [
    { test: /\.hbs$/, loader: 'handlebars-loader' }
  ]
},
plugins: [
  new HtmlWebpackPlugin({
    template: 'src/index.hbs'
  })
]

详细模板配置可参考docs/template-option.md。

高级功能

生成多页面应用

通过多次实例化插件生成多个HTML文件：

plugins: [
  new HtmlWebpackPlugin(), // 生成默认index.html
  new HtmlWebpackPlugin({  // 生成about.html
    filename: 'about.html',
    template: 'src/about.html',
    chunks: ['about'] // 只包含about chunk
  })
]

自定义模板参数

使用templateParameters选项传递自定义数据到模板：

new HtmlWebpackPlugin({
  template: 'src/index.html',
  templateParameters: {
    foo: 'bar',
    user: {
      name: 'John Doe'
    }
  }
})

在模板中使用：

<div><%= foo %></div>
<div><%= user.name %></div>

控制资源顺序

使用chunksSortMode控制chunk加载顺序：

new HtmlWebpackPlugin({
  chunksSortMode: 'manual',
  chunks: ['vendor', 'common', 'app']
})

实际案例

自定义模板示例

以下是使用自定义模板的Webpack配置：

webpack.config.js

const HtmlWebpackPlugin = require("html-webpack-plugin");
const MiniCssExtractPlugin = require("mini-css-extract-plugin");

module.exports = {
  entry: "./example.js",
  output: {
    path: __dirname + "/dist",
    filename: "bundle.js",
  },
  module: {
    rules: [
      { test: /\.css$/, use: [MiniCssExtractPlugin.loader, "css-loader"] },
      { test: /\.png$/, type: "asset/resource" },
    ],
  },
  plugins: [
    new HtmlWebpackPlugin({
      template: "template.html",
    }),
    new MiniCssExtractPlugin({ filename: "styles.css" }),
  ],
};

完整示例可参考examples/custom-template/webpack.config.js。

多页面应用配置

多页面应用配置示例：

module.exports = {
  entry: {
    home: './src/home.js',
    about: './src/about.js',
    contact: './src/contact.js'
  },
  output: {
    filename: '[name].bundle.js',
    path: __dirname + '/dist'
  },
  plugins: [
    new HtmlWebpackPlugin({
      filename: 'home.html',
      template: './src/home.html',
      chunks: ['home']
    }),
    new HtmlWebpackPlugin({
      filename: 'about.html',
      template: './src/about.html',
      chunks: ['about']
    }),
    new HtmlWebpackPlugin({
      filename: 'contact.html',
      template: './src/contact.html',
      chunks: ['contact']
    })
  ]
};

常见问题解决

资源路径问题

确保output.publicPath配置正确，特别是在生产环境部署时：

output: {
  publicPath: '/', // 或CDN地址
  filename: 'js/[name].[contenthash].js'
}

与其他插件配合

使用html-webpack-plugin时，通常需要与其他插件配合，如：

mini-css-extract-plugin：提取CSS到单独文件
copy-webpack-plugin：复制静态资源
favicons-webpack-plugin：生成各种尺寸的favicon

开发与生产环境差异

为不同环境创建不同配置：

const isProd = process.env.NODE_ENV === 'production';

new HtmlWebpackPlugin({
  minify: isProd ? {
    collapseWhitespace: true,
    removeComments: true,
    removeRedundantAttributes: true
  } : false,
  hash: isProd
})

总结

html-webpack-plugin是Webpack构建流程中不可或缺的工具，它简化了HTML文件的创建和资源管理。通过本文介绍的配置选项和高级功能，你可以轻松应对各种项目需求，从简单的单页应用到复杂的多页面网站。

建议结合官方示例库中的案例进行实践，探索更多高级用法。如有问题，可查阅项目README.md或提交issue获取帮助。

【免费下载链接】html-webpack-plugin 项目地址: https://gitcode.com/gh_mirrors/htm/html-webpack-plugin

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考