本文详解如何在 vite 中实现扁平化多 html 入口构建（如 dist/index.html、dist/about.html），避免默认的子目录嵌套结构，支持 js 打包与静态资源正确引用。
本文详解如何在 vite 中实现扁平化多 html 入口构建（如 dist/index.html、dist/about.html），避免默认的子目录嵌套结构，支持 js 打包与静态资源正确引用。
在传统构建工具（如 Gulp）迁移至 Vite 的过程中，一个常见需求是：将多个 HTML 文件（如 index.html、about.html、contact.html）作为独立入口，直接输出到 dist/ 根目录下，而非默认的 dist/about/index.html 模式。这种「扁平化多入口」结构对 SEO 友好、部署简单，且更贴近传统静态站点架构。
Vite 本身不原生提供「多 HTML 入口」的高层 API，但其底层基于 Rollup，可通过 build.rollupOptions.input 精确指定多个 HTML 入口文件，并结合 build.rollupOptions.output.entryFileNames（注意：此处需配合自定义插件或逻辑处理 HTML 输出路径）实现目标。⚠️需特别注意：entryFileNames 实际控制的是 JS/CSS 等资源文件名，而非 HTML 输出路径——HTML 文件的生成与重命名需通过插件或构建后处理完成。以下为推荐的可靠方案：
✅ 方案一：纯 Rollup 配置（适用于简单场景，HTML 内含内联或模块脚本）
// vite.config.ts
import { defineConfig } from 'vite';
export default defineConfig({
build: {
rollupOptions: {
// 显式声明多个 HTML 入口（Vite 会自动识别并处理其中的 <script type="module">）
input: ['src/index.html', 'src/about.html', 'src/contact.html'],
// ⚠️ 关键：禁用 chunk 分割，确保每个入口生成独立 JS（可选，按需启用）
output: {
manualChunks: undefined,
// entryFileNames 控制 JS 输出名，例如：'index.js' → 对应 index.html 引用
entryFileNames: (chunkInfo) => {
const name = chunkInfo.name.replace(/\.html$/, '');
return `${name}.js`;
}
}
}
}
});✅ 构建后效果：
- dist/index.html（自动注入 <script type="module" src="/index.js"></script>）
- dist/about.html（注入 <script type="module" src="/about.js"></script>）
- dist/contact.html（同理）
- dist/index.js, dist/about.js, dist/contact.js
✅ 方案二：使用 vite-plugin-multi-html（推荐，开箱即用）
为避免手动处理 HTML 路径映射与资源注入，建议使用社区成熟插件：
立即学习“前端免费学习笔记（深入）”；
npm install -D vite-plugin-multi-html
// vite.config.ts
import { defineConfig } from 'vite';
import multiHtml from 'vite-plugin-multi-html';
export default defineConfig({
plugins: [
multiHtml({
// 自动扫描 src/ 下所有 .html 文件作为入口（排除 index.html 若需单独配置）
entry: ['src/index.html', 'src/about.html', 'src/contact.html'],
// 输出时保持文件名扁平（默认行为）
flatten: true
})
]
});该插件会：
- 自动为每个 HTML 入口生成独立打包上下文；
- 正确注入对应入口 JS 资源（支持 HMR）；
- 保留原始 HTML 结构（包括 、 等）；
- 支持自定义模板变量与预处理器。
⚠️ 重要注意事项
- 静态 HTML 无需打包？→ 用 public/ 目录：若 HTML 不含任何 <script type="module"> 或动态逻辑，仅需原样复制，请直接放入 public/ 目录（如 public/about.html），Vite 会在构建时无修改地复制至 dist/。</script>
- CSS/JS 资源路径必须相对或绝对一致：确保 HTML 中引用的资源（如 ）与实际输出路径匹配；Vite 默认将静态资源输出至 dist/assets/，可通过 build.assetsDir 调整。
- 避免入口冲突：不要将 src/index.html 与其他 HTML 共享同一 JS 入口（如 main.ts），否则会因模块作用域重叠导致运行时错误；建议为每个 HTML 配置专属入口脚本（如 src/index.ts, src/about.ts）。
- 开发服务器支持：上述配置在 vite dev 下同样生效，访问 http://localhost:5173/about.html 可直接调试。
✅ 总结
实现 Vite 扁平化多 HTML 入口的核心在于：显式声明 rollupOptions.input + 合理配置资源输出策略 + 必要时引入专用插件。对于绝大多数项目，推荐采用 vite-plugin-multi-html 插件，兼顾简洁性、可维护性与稳定性；若追求零依赖，可基于原生 Rollup 配置深度定制。最终输出结构完全符合预期：dist/index.html、dist/about.html 等同级文件，干净、可控、易于部署。
