前端工程化 / 系统课时
构建多页面与库模式
构建多页面与库模式
本课解决两类容易混淆的生产构建:把多个 HTML 页面部署成站点,以及把源码打包成可被其他项目安装的库。完成后,你能为两种目标分别设置入口、外部依赖和输出格式,并通过产物目录快速判断配置是否正确。
学习目标
- 为多页面应用声明多个 HTML 入口并核对输出路径
- 使用 library mode 生成 ES 与 UMD 格式的库文件
- 判断依赖应该打入产物还是声明为外部依赖
先区分两种交付物
多页面应用的入口是 HTML,每个入口都会生成可直接访问的页面及其资源;库模式的入口是 JavaScript 或 TypeScript 模块,产物用于被其他项目导入,通常不包含应用页面。Vite 当前推荐用顶层 input 描述应用入口,用 build.lib 描述库入口,并通过 build.rolldownOptions 调整底层打包行为。:contentReference[oaicite:0]{index=0}
| 对比项 | 多页面应用 | 库模式 |
|---|---|---|
| 入口 | 一个或多个 HTML 文件 | 一个或多个 JS/TS 模块 |
| 主要产物 | HTML、哈希化 JS/CSS、静态资源 | ES、CJS、UMD 或 IIFE 模块 |
| 使用方式 | 浏览器直接访问页面 | 其他项目通过包管理器或脚本引入 |
| 依赖策略 | 通常随应用打包 | 框架等宿主依赖常设为 external |

配置多页面构建
假设项目根目录已有 index.html,管理端入口位于 admin/index.html。下面配置把两个绝对路径交给顶层 input,开发服务器和生产构建因此使用同一组入口。HTML 入口对象中的键主要用于配置识别,最终 HTML 路径仍按源文件相对结构生成。:contentReference[oaicite:1]{index=1}
// vite.mpa.config.ts
import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vite'
const fromRoot = (relativePath: string) =>
fileURLToPath(new URL(relativePath, import.meta.url))
export default defineConfig({
input: {
home: fromRoot('./index.html'),
admin: fromRoot('./admin/index.html'),
},
build: {
outDir: 'dist-mpa',
},
})这是完整配置示例,依赖项目中真实存在的两个 HTML 文件。构建后应得到 dist-mpa/index.html 与 dist-mpa/admin/index.html,两页引用的公共模块会由 Vite 统一处理,而不是复制两份源代码。
配置 library mode
库模式不能把 HTML 当作库入口。下面以 src/index.ts 为唯一入口,生成 ES 与 UMD 两种格式;vue 被设为外部依赖,因此不会进入库文件。UMD 在浏览器全局环境中运行时,需要通过 globals 把包名映射到宿主提供的 Vue 变量。:contentReference[oaicite:2]{index=2}
// vite.lib.config.ts
import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vite'
const entry = fileURLToPath(new URL('./src/index.ts', import.meta.url))
export default defineConfig({
build: {
outDir: 'dist-lib',
lib: {
entry,
name: 'WidgetKit',
formats: ['es', 'umd'],
fileName: (format) =>
format === 'es' ? 'widget-kit.js' : 'widget-kit.umd.cjs',
cssFileName: 'widget-kit',
},
rolldownOptions: {
external: ['vue'],
output: {
globals: {
vue: 'Vue',
},
},
},
},
})name 在 UMD 或 IIFE 输出中用于暴露全局变量;只发布 ES 或 CJS 时通常不需要它。被 external 的依赖必须由使用方安装并提供,发布包时应同步写入 peerDependencies,再用 exports 指向实际生成的文件。
构建并核对产物
项目的 package.json 需包含 "build": "vite build"。在项目根目录依次运行两个配置,并只列出本课关心的入口产物:
npm run build -- --config vite.mpa.config.ts
npm run build -- --config vite.lib.config.ts
find dist-mpa dist-lib -type f \( -name 'index.html' -o -name 'widget-kit.js' -o -name 'widget-kit.umd.cjs' \) | sort预期输出:
dist-lib/widget-kit.js
dist-lib/widget-kit.umd.cjs
dist-mpa/admin/index.html
dist-mpa/index.html实际构建还可能包含 assets/、CSS 和 sourcemap 文件。若缺少某个 HTML,先检查入口路径与大小写;若库文件仍包含 Vue 运行时代码,检查 external 的包名是否与源码中的导入名完全一致。
常见失败与边界
多页面入口不存在时,构建会在加载入口阶段失败;不要用一个不存在的别名路径代替真实文件路径。应用构建与库构建也不应共用同一个输出目录,否则后一次构建可能清空前一次产物。
外部依赖只是“不要打包”的声明,不会自动替使用方安装依赖。UMD/IIFE 还必须提供正确的全局变量映射;ES/CJS 由模块系统解析依赖,不读取 output.globals。