Vite 多入口 HTML 构建配置详解

本文深入解析了在 Vite 中实现扁平化多 HTML 入口构建的关键方法——让 index.html、about.html、contact.html 等多个页面直接输出到 dist/ 根目录下（如 dist/index.html、dist/about.html），彻底摆脱默认的嵌套子目录结构，兼顾 SEO 友好性、部署便捷性与传统静态站点习惯；文章不仅揭示了 Vite 原生配置的底层逻辑（通过 rollupOptions.input 精确控制入口+定制 entryFileNames 与构建后处理），更推荐开箱即用的 vite-plugin-multi-html 插件方案，同时厘清常见误区（如 HTML 路径与 JS 注入机制的区别）、强调静态资源路径一致性、专属入口脚本隔离等实战要点，助你高效、稳定地落地多页应用或内容型网站的现代化构建流程。

本文详解如何在 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（自动注入 ）
• dist/about.html（注入 ）
• 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 不含任何