2026/9/9 22:25:40
FEATURED · 精选文章 
Vite 插件如何用 transformIndexHtml 转换 HTML【免费下载链接】viteNext generation frontend tooling. Its fast!项目地址: https://gitcode.com/GitHub_Trending/vi/vite如果你的需求是在构建或开发过程中程序化地改写 HTML 入口文件——比如替换title、按构建状态向head注入script或link标签——就需要在 Vite 插件里实现transformIndexHtml钩子。这是 Vite 独有的插件钩子Rollup 会忽略它会在 dev 和 build 两种场景下自动作用于 HTML 入口文件如index.html。钩子是async、sequential调用的属于 per-environment 钩子。什么时候需要写这个钩子Vite 内置了简单的 HTML 常量替换任何import.meta.env中的属性都可以用%CONST_NAME%语法写进 HTML见 env-and-mode.mdh1Vite is running in %MODE%/h1 pUsing data from %VITE_API_URL%/p但 Vite 对条件分支这类复杂替换是刻意保持不干预的。当简单替换不够用时文档给出的扩展方式就是使用社区现成的转换类插件或自己写一个实现transformIndexHtml钩子 的自定义插件。两个前置结论先说明插件可以直接内联在vite.config.js里不需要为此新建一个包见 using-plugins.md。如果你使用的框架自己接管了入口文件文档以 SvelteKit 为例这个钩子不会被调用写之前先确认项目是否属于这种情况。最短主路径返回替换后的 HTML 字符串钩子接收当前 HTML 字符串和一个转换上下文最简单的写法是直接返回替换后的字符串以下示例来自 api-plugin.md 的官方示例const htmlPlugin () { return { name: html-transform, transformIndexHtml(html) { return html.replace( /title(.*?)\/title/, titleTitle replaced!/title, ) }, } }把它注册到vite.config.js的plugins数组即可import { defineConfig } from vite export default defineConfig({ plugins: [htmlPlugin()], })plugins中的 falsy 项会被忽略所以可以用条件表达式方便地启用/停用插件。三种返回值改字符串、注入标签、两者同时做钩子可以返回以下三者之一转换后的 HTML 字符串——上面的标题替换例子标签描述对象数组{ tag, attrs, children }——注入到现有 HTML 中每个标签可单独指定注入位置默认注入到head的开头同时包含两者的对象{ html, tags }。标签描述符的完整类型如下来自文档的 Full Hook Signaturetype IndexHtmlTransformHook ( html: string, ctx: { path: string filename: string server?: ViteDevServer bundle?: import(rolldown).OutputBundle chunk?: import(rolldown).OutputChunk originalUrl?: string }, ) IndexHtmlTransformResult | void | PromiseIndexHtmlTransformResult | void type IndexHtmlTransformResult | string | HtmlTagDescriptor[] | { html: string tags: HtmlTagDescriptor[] } interface HtmlTagDescriptor { tag: string /** * attribute values will be escaped automatically if needed */ attrs?: Recordstring, string | boolean children?: string | HtmlTagDescriptor[] /** * default: head-prepend */ injectTo?: head | body | head-prepend | body-prepend }其中attrs的值在需要时会被自动转义。第二个参数ctx在 dev 时暴露ViteDevServer实例在 build 时暴露输出 bundle——也就是说同一个钩子函数可以按运行阶段读取不同的上下文信息完整类型声明见 api-plugin.md。用order控制钩子的执行时机钩子也可以写成对象形式IndexHtmlTransformHook | { order?: pre | post, handler: IndexHtmlTransformHook }。默认order为undefined钩子在 HTML 已被转换之后应用order: pre在 Vite 处理 HTML 之前应用文档明确给出的用途是注入需要经过 Vite 插件流水线的 scriptorder: post在所有order为 undefined 的钩子之后应用。const myPlugin () ({ name: inject-pre-script, transformIndexHtml: { order: pre, handler(html) { return [{ tag: script, attrs: { src: /entry.js } }] }, }, })注意这和插件级的enforce: pre | post调整整个插件相对 Vite 核心插件的位置是两回事见 api-plugin.md 的 Plugin Ordering 一节。如何验证转换生效钩子在 dev 和 build 下都会被调用Vite 插件的默认行为是两种场景都执行所以验证分两条dev启动开发服务器后直接访问入口 HTML 页面检查渲染出的title、注入的标签是否按预期出现order: pre注入的 script 应当走 Vite 的模块处理流程。build运行构建命令检查产物中对应 HTML 文件里的替换/注入结果确认钩子在构建阶段同样生效。调试插件时文档建议把vite-plugin-inspect加入项目安装后访问localhost:5173/__inspect/可以检查模块和转换栈的中间状态。边界与限制框架接管入口文件时钩子不触发文档特别警告若框架对入口文件有自定义处理例如 SvelteKittransformIndexHtml不会被调用。钩子作用域是 per-environment跨环境行为以 api-environment-plugins.md 的说明为准。%CONST_NAME%不存在的变量不会被替换保留原样这与 JS 中import.meta.env.X得到undefined的行为不同复杂逻辑不要指望它交给本钩子。另有一个同名程序化 API自定义 SSR 中间件里可以用vite.transformIndexHtml(url, template)手动对模板应用 Vite 内置 HTML 转换和插件 HTML 转换见 ssr.md 与 api-javascript.md。那是服务端渲染中间件场景的用法与插件钩子本身是不同入口按需选择。【免费下载链接】viteNext generation frontend tooling. Its fast!项目地址: https://gitcode.com/GitHub_Trending/vi/vite创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Vite 插件如何用 transformIndexHtml 转换 HTML？
Vite 插件如何用 transformIndexHtml 转换 HTML【免费下载链接】viteNext generation frontend tooling. Its fast!项目地址: https://gitcode.com/GitHub_Trending/vi/vite如果你的需求是在构建或开发过程中程序化地改写 HTML 入口文件——比如替换title、按构建状态向head注入script或link标签——就需要在 Vite 插件里实现transformIndexHtml钩子。这是 Vite 独有的插件钩子Rollup 会忽略它会在 dev 和 build 两种场景下自动作用于 HTML 入口文件如index.html。钩子是async、sequential调用的属于 per-environment 钩子。什么时候需要写这个钩子Vite 内置了简单的 HTML 常量替换任何import.meta.env中的属性都可以用%CONST_NAME%语法写进 HTML见 env-and-mode.mdh1Vite is running in %MODE%/h1 pUsing data from %VITE_API_URL%/p但 Vite 对条件分支这类复杂替换是刻意保持不干预的。当简单替换不够用时文档给出的扩展方式就是使用社区现成的转换类插件或自己写一个实现transformIndexHtml钩子 的自定义插件。两个前置结论先说明插件可以直接内联在vite.config.js里不需要为此新建一个包见 using-plugins.md。如果你使用的框架自己接管了入口文件文档以 SvelteKit 为例这个钩子不会被调用写之前先确认项目是否属于这种情况。最短主路径返回替换后的 HTML 字符串钩子接收当前 HTML 字符串和一个转换上下文最简单的写法是直接返回替换后的字符串以下示例来自 api-plugin.md 的官方示例const htmlPlugin () { return { name: html-transform, transformIndexHtml(html) { return html.replace( /title(.*?)\/title/, titleTitle replaced!/title, ) }, } }把它注册到vite.config.js的plugins数组即可import { defineConfig } from vite export default defineConfig({ plugins: [htmlPlugin()], })plugins中的 falsy 项会被忽略所以可以用条件表达式方便地启用/停用插件。三种返回值改字符串、注入标签、两者同时做钩子可以返回以下三者之一转换后的 HTML 字符串——上面的标题替换例子标签描述对象数组{ tag, attrs, children }——注入到现有 HTML 中每个标签可单独指定注入位置默认注入到head的开头同时包含两者的对象{ html, tags }。标签描述符的完整类型如下来自文档的 Full Hook Signaturetype IndexHtmlTransformHook ( html: string, ctx: { path: string filename: string server?: ViteDevServer bundle?: import(rolldown).OutputBundle chunk?: import(rolldown).OutputChunk originalUrl?: string }, ) IndexHtmlTransformResult | void | PromiseIndexHtmlTransformResult | void type IndexHtmlTransformResult | string | HtmlTagDescriptor[] | { html: string tags: HtmlTagDescriptor[] } interface HtmlTagDescriptor { tag: string /** * attribute values will be escaped automatically if needed */ attrs?: Recordstring, string | boolean children?: string | HtmlTagDescriptor[] /** * default: head-prepend */ injectTo?: head | body | head-prepend | body-prepend }其中attrs的值在需要时会被自动转义。第二个参数ctx在 dev 时暴露ViteDevServer实例在 build 时暴露输出 bundle——也就是说同一个钩子函数可以按运行阶段读取不同的上下文信息完整类型声明见 api-plugin.md。用order控制钩子的执行时机钩子也可以写成对象形式IndexHtmlTransformHook | { order?: pre | post, handler: IndexHtmlTransformHook }。默认order为undefined钩子在 HTML 已被转换之后应用order: pre在 Vite 处理 HTML 之前应用文档明确给出的用途是注入需要经过 Vite 插件流水线的 scriptorder: post在所有order为 undefined 的钩子之后应用。const myPlugin () ({ name: inject-pre-script, transformIndexHtml: { order: pre, handler(html) { return [{ tag: script, attrs: { src: /entry.js } }] }, }, })注意这和插件级的enforce: pre | post调整整个插件相对 Vite 核心插件的位置是两回事见 api-plugin.md 的 Plugin Ordering 一节。如何验证转换生效钩子在 dev 和 build 下都会被调用Vite 插件的默认行为是两种场景都执行所以验证分两条dev启动开发服务器后直接访问入口 HTML 页面检查渲染出的title、注入的标签是否按预期出现order: pre注入的 script 应当走 Vite 的模块处理流程。build运行构建命令检查产物中对应 HTML 文件里的替换/注入结果确认钩子在构建阶段同样生效。调试插件时文档建议把vite-plugin-inspect加入项目安装后访问localhost:5173/__inspect/可以检查模块和转换栈的中间状态。边界与限制框架接管入口文件时钩子不触发文档特别警告若框架对入口文件有自定义处理例如 SvelteKittransformIndexHtml不会被调用。钩子作用域是 per-environment跨环境行为以 api-environment-plugins.md 的说明为准。%CONST_NAME%不存在的变量不会被替换保留原样这与 JS 中import.meta.env.X得到undefined的行为不同复杂逻辑不要指望它交给本钩子。另有一个同名程序化 API自定义 SSR 中间件里可以用vite.transformIndexHtml(url, template)手动对模板应用 Vite 内置 HTML 转换和插件 HTML 转换见 ssr.md 与 api-javascript.md。那是服务端渲染中间件场景的用法与插件钩子本身是不同入口按需选择。【免费下载链接】viteNext generation frontend tooling. Its fast!项目地址: https://gitcode.com/GitHub_Trending/vi/vite创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
