前端工程化 / 系统课时

构建多页面与库模式

构建多页面与库模式

本课解决两类容易混淆的生产构建:把多个 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}

ts
// 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}

ts
// 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"。在项目根目录依次运行两个配置,并只列出本课关心的入口产物:

bash
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

预期输出:

text
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。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

构建多页面与库模式

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通