@eason627/single-html-builder

为 Vite 项目生成可直接双击打开的预览 HTML，适用于 file:// 场景下的本地预览与交付。

安装

npm i -D @eason627/single-html-builder

安装后会自动尝试在业务项目的 package.json 中注入：

• scripts.build:single

如果你不想依赖自动注入，也可以手动添加：

{
  "scripts": {
    "build:single": "vite-single-preview-builder"
  }
}

用法

执行：

npm run build:single

执行后会先在命令行输出本次构建的关键信息：

• 当前识别到的框架
• 入口文件
• 路由文件
• 资源目录
• 扫描范围
• 构建产物目录
• 预览输出目录
• 输出文件名
• 资源模式
• 图片等资源内联阈值
• 外置资源目录
• 资源物理输出目录
• 下载资源目录
• 下载资源处理方式
• 待下载的外部资源 URL

随后会询问：

是否将下载的本地资源以内联 data: 方式打包进去？(y/n，默认 y)

• 输入 y：将下载下来的本地资源尽量转成 data: 内联进最终 HTML
• 输入 n：最终 HTML 将引用输出资源目录中的文件路径

选择 n 时，命令行会额外提示你：

• 需要同时移动预览 HTML 和资源目录
• 建议在 package.json 中显式配置 outputDir 和 externalAssetDir

确认无误后按回车，才会正式开始打包。

默认行为

默认流程如下：

1. 本地化外部资源
2. 单文件模式构建
3. 智能处理资源并输出预览 HTML

默认情况下：

• 构建产物目录：沿用 Vite 原本配置，未配置时通常为 dist/
• 预览输出目录：项目根目录
• 单文件预览页：【双击预览】.html
• 公共资源目录：public/
• 资源扫描范围：index.html、src、public
• 资源模式：smart
• 下载资源目录：external-assets
• 外置资源目录：【双击预览】_assets
• 资源物理输出目录：默认跟随 outputDir
• 体积超过 256 KB 的图片、音视频等资源默认不会继续内联进 HTML，而是输出到资源目录

自动识别

当前版本会自动识别项目环境，尽量做到零配置可用：

• 自动识别 vue / react
• 自动识别常见入口文件
• Vue 项目自动识别常见路由文件
• 自动扫描源码中的外部资源引用
• 自动下载并本地化外链 CSS、字体、图片等资源
• 最终优先内联关键资源，并自动拆分体积过大的静态资源，避免单文件产物失控

Vue 项目常见入口识别优先级：

• src/main.ts
• src/main.js
• src/main.mts
• src/main.mjs
• src/main.tsx
• src/main.jsx

React 项目常见入口识别优先级：

• src/App.tsx
• src/App.jsx
• src/App.ts
• src/App.js
• src/main.tsx
• src/main.jsx

配置

大多数项目不需要配置，零配置即可使用。

如需覆盖默认行为，可在业务项目 package.json 中增加：

{
  "singlePreviewBuilder": {
    "framework": "vue",
    "appEntry": "src/main.ts",
    "routerEntry": "src/router/index.ts",
    "outDir": "dist",
    "publicDir": "public",
    "outputDir": ".",
    "outputFile": "【双击预览】.html",
    "assetMode": "smart",
    "inlineAssetMaxSize": 262144,
    "inlineAssetExtensions": [".svg", ".woff2", ".woff", ".ttf", ".css", ".js"],
    "externalAssetDir": "【双击预览】_assets",
    "assetOutputDir": ".",
    "downloadedAssetDir": "external-assets",
    "downloadedAssetMode": "inline",
    "sourceRoots": ["index.html", "src", "public"]
  }
}

配置项说明：

• framework: 指定框架，可选 vue、react、auto，默认 auto
• appEntry: 指定应用入口文件
• routerEntry: 指定路由文件，当前主要用于 Vue Router 场景
• outDir: 指定构建产物目录；如果不填，优先沿用业务项目的 Vite 配置
• publicDir: 公共资源目录，默认 public
• outputDir: 预览 HTML 的输出目录，默认项目根目录
• outputFile: 最终预览文件名称，默认 【双击预览】.html
• assetMode: 资源处理模式，默认 smart；可选 smart、inline-all
• inlineAssetMaxSize: 智能模式下的内联阈值，默认 262144
• inlineAssetExtensions: 始终优先内联的扩展名列表
• externalAssetDir: 非内联资源的输出目录，默认 【双击预览】_assets
• assetOutputDir: 资源物理输出目录，默认跟随 outputDir；如需把资源留在项目原目录，可显式设为 .
• downloadedAssetDir: 识别“下载的本地资源”所用的目录名，默认 external-assets
• downloadedAssetMode: 下载资源默认处理方式，默认 inline；运行时可通过命令行 y/n 临时覆盖
• sourceRoots: 扫描外部资源引用的根路径列表

兼容说明

当前版本重点兼容以下场景：

• Vite + Vue
• Vite + React
• Next.js 静态导出产物
• Vue Router 本地预览
• React Router 本地预览
• 外链 CSS / 字体 / 图片资源的本地化与处理
• 大图片资源自动拆分，避免最终 HTML 体积过大

当前版本不直接支持：

• 非 Vite 构建体系
• Next.js SSR / 服务端运行模式
• 未开启 output: 'export' 的 Next.js 项目

注意事项

• 建议在发布前先执行一次 npm run build:single 本地验证最终 HTML
• 如果页面存在大量图片、视频、音频资源，建议保持默认 smart 模式
• 如果输入 n，最终预览文件不再是绝对单文件，必须和 externalAssetDir 一起移动
• 如果你计划把 HTML 输出到别处、但资源仍留在项目原目录，可显式配置 outputDir 和 assetOutputDir
• inline-all 更适合纯演示页或资源很少的页面，不适合包含大量素材的业务系统
• 如果业务项目中存在大量运行时动态加载资源，仍需单独确认这些资源是否能在 file:// 场景下工作
• 若业务项目使用了非常规入口结构，建议显式配置 appEntry 或 routerEntry
• 若你升级了包但没有看到新行为，请确认业务项目里安装的是最新版本依赖