简体中文

HtmlRspackPlugin

Rspack only

rspack.HtmlRspackPlugin 是使用 Rust 实现的高性能 HTML 插件，你可以使用它来为 Rspack 项目生成 HTML 文件。

new rspack.HtmlRspackPlugin(options);

对比

在使用 rspack.HtmlRspackPlugin 之前，请注意 rspack.HtmlRspackPlugin 和社区的 html-webpack-plugin 插件存在一些差异。

性能

由于 rspack.HtmlRspackPlugin 是基于 Rust 实现的，因此它的构建性能显著高于 html-webpack-plugin 插件，尤其是在构建大量 HTML 文件的场景下。

功能

rspack.HtmlRspackPlugin 的功能是 html-webpack-plugin 的子集。为了保证插件的性能，我们没有实现 html-webpack-plugin 提供的所有功能。

如果它提供的配置项无法满足你的需求，你也可以直接使用社区的 html-webpack-plugin 插件。

WARNING

rspack.HtmlRspackPlugin 不支持完整的 EJS 语法, 仅支持 EJS 语法的一个子集，如果你对完整的 EJS 语法支持有需求，可以直接使用 html-webpack-plugin。为了和 html-webpack-plugin 的默认的插值语法对齐， Rspack 修改了 EJS 的 escape 和 unescape 的默认语法，使其采用和 html-webpack-plugin 相同的语法。

支持的 EJS 语法

仅支持如下基本的插值表达式,这里的插值表达式只支持最基本的字符串类型，不支持任意的 JavaScript 表达式，其他的 ejs 语法目前均不支持。

<%-: Escaped output

对插值内容进行 escape：

ejs

<p>Hello, <%- name %>.</p>
<p>Hello, <%- 'the Most Honorable ' + name %>.</p>

locals

{
  "name": "Rspack<y>"
}

html

<p>Hello, Rspack&lt;y&gt;.</p>
<p>Hello, the Most Honorable Rspack&lt;y&gt;.</p>

<%=: Unescaped output

不对插值内容进行 escape：

ejs

<p>Hello, <%- myHtml %>.</p>
<p>Hello, <%= myHtml %>.</p>

<p>Hello, <%- myMaliciousHtml %>.</p>
<p>Hello, <%= myMaliciousHtml %>.</p>

locals

{
  "myHtml": "<strong>Rspack</strong>",
  "myMaliciousHtml": "</p><script>document.write()</script><p>"
}

html

<p>Hello, &lt;strong&gt;Rspack&lt;/strong&gt;.</p>
<p>Hello, <strong>Rspack</strong>.</p>

<p>Hello, &lt;/p&gt;&lt;script&gt;document.write()&lt;/script&gt;&lt;p&gt;.</p>
<p>Hello,</p>
<script>
  document.write();
</script>
<p>.</p>

用法

这个插件会为你生成一个 HTML 文件，该文件的 head 包含了所有 JS 产物对应的 <script> 标签。

只需像这样，将插件添加到你的 Rspack 配置中：

rspack.config.js

const rspack = require('@rspack/core');

module.exports = {
  plugins: [new rspack.HtmlRspackPlugin()],
};

这将生成一个包含以下内容的 dist/index.html 文件：

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

如果你的 Rspack 配置中有多个 entry points，它们的生成 <script> 标签都会被包含在这个 HTML 文件中。

如果你的构建产物中有一些 CSS 资源，它们将被包含在 HTML head 的 <link> 标签中。

选项

你可以向 rspack.HtmlRspackPlugin 传递一些配置项，支持的选项如下：

类型：

type HtmlRspackPluginOptions = {
  title?: string;
  filename?: string;
  template?: string;
  templateContent?: string;
  templateParameters?: Record<string, string>;
  inject?: 'head' | 'body';
  publicPath?: string;
  scriptLoading?: 'blocking' | 'defer' | 'module';
  chunks?: string[];
  excludeChunks?: string[];
  sri?: 'sha256' | 'sha384' | 'sha512';
  minify?: boolean;
  favicon?: string;
  meta?: Record<string, string | Record<string, string>>;
};

默认值： {}

名称	类型	默认值	描述
`title`	`string\|undefined`	undefined	构建 HTML 的标题
`filename`	`string`	'index.html'	输出的文件名，可以指定子目录，例如 `pages/index.html`
`template`	`string\|undefined`	undefined	模版文件路径，支持 ejs
`templateContent`	`string\|undefined`	undefined	模版文件内容，优先级大于 template
`templateParameters`	`Record<string, string>`	{}	传递给模版的参数
`inject`	`'head'\|'body'\|undefined`	undefined	产物注入位置
`publicPath`	`string`	''	script 和 link 标签的 publicPath
`scriptLoading`	`'blocking'\|'defer'\|'module'`	'defer'	现代浏览器支持使用 defer 来异步加载 js，设置为 module 则会添加 `type="module"` 同时使用 defer
`chunks`	`string[]\|undefined`	undefined	配置需要注入的 chunk，默认注入所有 chunk
`excludeChunks`	`string[]\|undefined`	undefined	配置需要跳过注入的 chunk
`sri`	`'sha256'\|'sha384'\|'sha512'\|undefined`	undefined	sri hash 算法，默认不开启 sri
`minify`	`boolean`	false	是否启用压缩
`favicon`	`string\|undefined`	undefined	配置 HTML 图标
`meta`	`Record<string, string\|Record<string, string>>`	{}	配置需要注入 HTML 的 meta

示例

自定义 HTML 模板

如果默认生成的 HTML 不符合你的需求，你可以使用自己的模板。

最简单的方式是使用 template 选项，并传递一个自定义的 HTML 文件。rspack.HtmlRspackPlugin 将会自动将所有需要的 JS、CSS 和 favicon 文件注入到 HTML 中。

创建 index.html 文件：

index.html

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>My HTML Template</title>
  </head>
  <body></body>
</html>

设置 template 选项：

rspack.config.js

const rspack = require('@rspack/core');

module.exports = {
  plugins: [
    new rspack.HtmlRspackPlugin({
      template: 'index.html',
    }),
  ],
};

生成多个 HTML 文件

如果你有多个 entry points，并希望为每个 entry 生成一个 HTML 文件，那么你可以注册多个 rspack.HtmlRspackPlugin：

使用 filename 来为每个 HTML 文件指定名称。
使用 chunks 来为每个 HTML 文件指定需要包含的 JS 产物。

比如以下配置，会生成 foo.html 和 bar.html，其中 foo.html 仅会包含 foo.js 生成的 JS 产物。

const rspack = require('@rspack/core');

module.exports = {
  entry: {
    foo: './foo.js',
    bar: './bar.js',
  },
  plugins: [
    new rspack.HtmlRspackPlugin({
      filename: 'foo.html',
      chunks: ['foo'],
    }),
    new rspack.HtmlRspackPlugin({
      filename: 'bar.html',
      chunks: ['bar'],
    }),
  ],
};

ON THIS PAGE

HtmlRspackPlugin#

对比#

性能#

功能#

支持的 EJS 语法#

<%-: Escaped output#

<%=: Unescaped output#

用法#

选项#

示例#

自定义 HTML 模板#

生成多个 HTML 文件#