配置 HTML 模板
在构建的过程中，Rsbuild 会基于 HTML 模板文件和模板参数进行编译，生成若干份 HTML 文件。
Rsbuild 提供了一些配置项来对 HTML 模板进行设置。通过本章节你可以了解到这些配置项的基本用法。
设置模板文件
在 Rsbuild 中，你可以使用 html.template 配置项来设置自定义的 HTML 模板文件。
export default { html: { template: './static/index.html', }, };
未设置 html.template 时，Rsbuild 会使用内置的 HTML 模板：
defaultTemplate.html
<!doctype html> <html> <head></head> <body> <div id="<%= mountId %>"></div> </body> </html>
设置页面标题
你可以通过 html.title 配置项来设置 HTML 的 <title> 标签。
当你的项目中只有一个页面时，直接使用 html.title 设置即可：
export default { html: { title: 'example', }, };
当你的项目中有多个页面时，可以基于入口名称，来为不同的页面设置对应的标题。
export default { html: { title({ entryName }) { const titles = { foo: 'Foo', bar: 'Bar', }; return titles[entryName]; }, }, };
TIP
对于单页应用（SPA），Rsbuild 会在 HTML 页面中包含一个初始的 title，但你通常需要在路由切换时动态更新页面标题，例如使用一些路由库，或是 React Helmet 这类库。
设置页面图标
Rsbuild 支持设置 favicon 图标 和 iOS 系统下的 apple-touch-icon 图标。
你可以通过 html.favicon 配置项来设置 favicon 图标。
export default { html: { favicon: './src/assets/icon.png', }, };
你也可以通过 html.appIcon 配置项来设置 Web 应用的图标，用于在添加到移动设备的主屏幕时显示。
export default { html: { appIcon: { name: 'My Website', icons: [ { src: './src/assets/logo-192.png', size: 192 }, { src: './src/assets/logo-512.png', size: 512 }, ], }, }, };
设置 meta 标签
你可以通过 html.meta 配置项来设置 HTML 的 <meta> 标签。
Rsbuild 默认设置了 charset 和 viewport meta 标签：
<meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" />
你也可以添加自定义的 meta 标签，比如设置 description：
export default { html: { meta: { description: 'a description of the page', }, }, };
最终在 HTML 中生成的 meta 标签为：
<meta name="description" content="a description of the page" />
默认模板引擎
Rsbuild 内置了一个默认的模板引擎来处理 HTML 模板文件，它的语法接近 EJS 的子集，但也有一些不同。当 HTML 模板文件的后缀为 .html 时，Rsbuild 会使用内置的模板引擎来解析 HTML 模板。
例如，在模板中定义一个 text 参数，值为 'world'。Rsbuild 在构建时会自动将 <%= text %> 替换为指定的值。
<!-- 输入 --> <div>hello <%= text %>!</div> <!-- 输出 --> <div>hello world!</div>
模板参数
在 HTML 模板中，你可以使用丰富的模板参数，Rsbuild 默认注入的模板参数包括：
type DefaultParameters = { mountId: string; // 对应 html.mountId 配置 entryName: string; // 入口名称 assetPrefix: string; // 对应 dev.assetPrefix 和 output.assetPrefix 配置 compilation: Compilation; // 对应 Rspack 的 compilation 对象 rspackConfig: Rspack.Configuration; // Rspack 的配置对象 // html-rspack-plugin 生成的参数 htmlPlugin: { tags: { headTags: HtmlTagObject[]; bodyTags: HtmlTagObject[]; }; files: { publicPath: string; js: Array<string>; css: Array<string>; favicon?: string; }; }; };
你可以通过 html.templateParameters 配置项来传入自定义的模板参数，比如：
rsbuild.config.ts
export default { html: { templateParameters: { text: 'world', }, }, };
接下来，你可以在 HTML 模板中，通过 <%= text %> 来读取参数：
index.html
<div>hello <%= text %>!</div>
编译后的 HTML 代码如下：
参数转义
使用 <%= text %> 时，参数不会被转义。你可以使用 <%- text %> 来 escape 参数。
比如参数 text 的值是 '<script>'，则会被转义为 <script>：
<!-- 输入 --> <div>hello <%- text %>!</div> <!-- 输出 --> <div>hello <script>!</div>
TIP
注意，Rsbuild 默认的转义语法是与 EJS 不同的。在 EJS 中，默认的转义语法是 <%= text %>，而 Rsbuild 的默认转义语法是 <%- text %>。
其他模板引擎
Rsbuild 也支持通过插件来使用其他模板引擎，如 EJS、Pug 等。
EJS
Rsbuild 内置的模板语法与 EJS 存在一些差异，如果你需要使用完整的 EJS 语法，可以通过插件来支持，详见 rsbuild-plugin-ejs。
Pug
Rsbuild 通过插件来支持 Pug 模板引擎，详见 @rsbuild/plugin-pug。
注入标签
通过配置 html.tags 选项，可以在 Rsbuild 生成的 HTML 文件中插入任意标签。
在 HTML 的模版中，可以通过 htmlPlugin.tags 变量来访问被注入到 HTML 的所有标签：
index.html
<html> <head> <%= htmlPlugin.tags.headTags %> </head> <body> <div id="root"></div> <%= htmlPlugin.tags.bodyTags %> </body> </html>
html.tags 的作用就是调整这些 tags 变量，从而修改 HTML 里的标签，下面是一个基本的例子：
export default { html: { tags: [ { tag: 'script', attrs: { src: 'https://cdn.example.com/my-script.js' } }, ], }, };
<html> <head> <script src="https://cdn.example.com/my-script.js"></script> <!-- some other headTags... --> </head> <body> <!-- some other bodyTags... --> </body> </html>
更多用法请参考：html.tags。
TIP
通常你不需要手动使用 htmlPlugin.tags.headTags 和 htmlPlugin.tags.bodyTags 模板参数，因为 Rsbuild 会自动注入这些标签。参考 html.inject 了解调整标签注入位置。
HTML 插件
Rsbuild 内部基于 html-rspack-plugin 实现 HTML 相关的能力。它是 html-webpack-plugin 的一个 fork 版本，具备完全一致的功能和选项。
你可以通过 tools.htmlPlugin 来修改 html-rspack-plugin 的选项，也可以禁用内置的 html-rspack-plugin 插件。
比如：
rsbuild.config.ts
export default { tools: { htmlPlugin(config, { entryName }) { if (process.env.NODE_ENV === 'production') { config.filename = `${entryName}.[contenthash:8].html`; } }, }, };
HTML 压缩
Rsbuild 目前不对 HTML 文件进行压缩，如果你需要压缩 HTML 文件，可以使用 rsbuild-plugin-html-minifier-terser 插件。
