12.6 阶段 5 构建工具链与工程化(Vite 5 / monorepo)
本页目录
一、阶段定位
本阶段解决「工程怎么从单文件长成多人协作的大型应用」:Vite 5 配置、环境变量、路径别名、代码分割、ESLint/Prettier 统一规范、pnpm workspace monorepo 多包协作。很多人会用 Vite 起项目,但一问「为什么 build 后首屏慢、怎么拆包、环境变量怎么读、monorepo 里包怎么互相引用」就卡壳。
不掌握本阶段会在后面具体卡在哪:
- 把所有依赖打进一个 bundle,首屏 JS 几兆,Lighthouse 分数惨不忍睹,不知道 manualChunks 怎么配。
- 开发与生产接口地址写死在代码里,换环境要改源码,不知道
.env文件与import.meta.env。 - 多人协作代码风格不一,空格分号引号各写各的,没有 ESLint/Prettier 与提交校验。
- 多个项目要共享一个组件库,只能复制粘贴,不知道 pnpm workspace 怎么建内部包。
判断卡住的标志:让你解释 Vite 开发期与生产期分别用什么打包、为什么不一样;或让你把 React 与 vendor 拆成两个 chunk;或你不知道 .env.development 与 .env.production 怎么生效。出现任一现象,先把本阶段六个模块过一遍再进 阶段 6 Node BFF 与 SSR。
二、阶段目标与投入
| 能力目标(可验证的行为) | 验证方式 |
|---|---|
| 能配置 Vite 的别名、代理、构建拆包 | vite build 产物有独立 vendor chunk |
能用 .env 管理多环境变量 |
开发/生产接口地址不同且代码同一份 |
| 能配 ESLint + Prettier + 提交钩子 | 提交时自动格式化与 lint |
| 能建 pnpm workspace monorepo | 两个内部包互相引用、共享类型 |
| 能做代码分割与路由懒加载 | 首屏 bundle 显著减小 |
| 能看懂打包产物与 sourcemap | 在 dist 里指出 chunk 关系 |
建议学时:
- 全职:2 周,约 35 小时。Vite 配置 8 小时、环境变量与代理 4 小时、ESLint/Prettier/Git 钩子 8 小时、monorepo 10 小时、拆包与产物分析 5 小时。
- 在职:4 周,约 40 小时。
三、先修自检
| 先修项 | 合格标准 | 不合格时怎么办 |
|---|---|---|
| 阶段 0 产出 | 能用 Vite 起项目、pnpm 装依赖 | 回到 12.1 |
| TS | 能配 tsconfig 与 paths | 回到 12.3 |
四、知识地图
| 模块 | 知识点 | 掌握程度 | 对应题库章节 |
|---|---|---|---|
| Vite 配置 | resolve.alias、server.proxy、build.rollupOptions、manualChunks | 能讲清原理 | 03.6 前端工程化 |
| 环境变量 | .env、import.meta.env、模式 mode |
会用 | 03.6 前端工程化 |
| 代码质量 | ESLint、Prettier、EditorConfig、lint-staged、husky | 会用 | 03.6 前端工程化 |
| monorepo | pnpm workspace、内部包、版本共享、Turborepo/Nx(了解) | 会用 | 03.6 前端工程化 |
| 代码分割 | 路由懒加载、动态 import、vendor 拆包 | 会用 | 03.6 前端工程化 |
| 产物分析 | sourcemap、chunk 关系、bundle 体积分析 | 了解 | 03.8 浏览器原理、性能优化与前端安全 |
五、分模块精讲
5.1 Vite 配置:别名、代理、拆包
为什么需要它:默认配置能跑,但真实项目要配别名、代理、拆包,否则路径丑、跨域、首屏慢。
核心机制:
resolve.alias:@指向src,与 tsconfig paths 对应。server.proxy:开发期把/api代理到后端,解决跨域。build.rollupOptions.output.manualChunks:把 node_modules 里的大依赖(react、vue、echarts)拆成独立 chunk,利用浏览器缓存。
最小可运行示例:
// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { fileURLToPath, URL } from 'node:url'
export default defineConfig({
plugins: [vue()],
resolve: {
alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) }
},
server: {
port: 5173,
proxy: {
'/api': { target: 'http://localhost:8080', changeOrigin: true, rewrite: p => p.replace(/^\/api/, '') }
}
},
build: {
rollupOptions: {
output: {
manualChunks: {
vue: ['vue', 'vue-router', 'pinia'],
vendor: ['axios', 'lodash-es']
}
}
}
}
})
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 别名构建报错 | tsconfig paths 与 vite alias 不一致 | 两边都配 |
| 代理 404 | rewrite 把路径改错了 | 看代理日志 |
| chunk 拆太碎 | 拆得过细 | 按大依赖合并 |
面试考法:问 Vite 与 Webpack 区别。答到:开发期 Vite 用原生 ESM 不打包,Webpack 要先 bundle;生产期都用 Rollup/webpack 打包。
5.2 环境变量
为什么需要它:开发/测试/生产的接口地址、埋点 key、功能开关不同,不能写死。
核心机制:
.env、.env.development、.env.production:Vite 按 mode 自动加载;只有以VITE_开头的变量暴露给客户端代码。- 代码里用
import.meta.env.VITE_API_BASE读取;import.meta.env.DEV/PROD/MODE是内置的。 - 敏感密钥(服务端用的)不要以
VITE_开头,否则会打进前端包。
最小可运行示例:
# .env.development
VITE_API_BASE=/api
VITE_APP_TITLE=本地环境
# .env.production
VITE_API_BASE=https://api.example.com
VITE_APP_TITLE=生产环境
// src/env.d.ts
/// <reference types="vite/client" />
interface ImportMetaEnv {
readonly VITE_API_BASE: string
readonly VITE_APP_TITLE: string
}
interface ImportMeta { readonly env: ImportMetaEnv }
const base = import.meta.env.VITE_API_BASE
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 变量是 undefined | 没以 VITE_ 开头 | 重命名 |
| 改了 env 不生效 | dev server 没重启 | 重启 Vite |
| 密钥泄露 | 把服务端密钥加了 VITE_ | 去掉前缀,只放服务端 |
面试考法:问为什么只有 VITE_ 开头暴露。答到:避免把服务端机密打进前端包,Vite 静态替换白名单。
5.3 ESLint + Prettier + Git 钩子
为什么需要它:多人协作统一风格,把「空格分号引号」这类争论从 code review 里去掉,提交前自动检查。
核心机制:
- ESLint 查代码质量(未用变量、eqeqeq、hooks 依赖);Prettier 管格式(缩进、引号、分号);两者配合不冲突(ESLint 关掉格式规则)。
- husky 挂 Git 钩子:
pre-commit跑 lint-staged 只检查暂存文件;commit-msg校验提交信息(可选 conventional commits)。 - EditorConfig 统一编辑器换行与缩进。
最小可运行示例:
pnpm add -D eslint prettier @typescript-eslint/parser eslint-config-prettier husky lint-staged
pnpm exec husky init
# 生成 .husky/pre-commit,内容:
# pnpm exec lint-staged
// .lintstagedrc.json
{
"*.{ts,tsx,vue}": ["eslint --fix", "prettier --write"],
"*.{md,json}": ["prettier --write"]
}
// eslint.config.js(Flat Config,ESLint 9)
import js from '@eslint/js'
import tseslint from 'typescript-eslint'
import prettier from 'eslint-config-prettier'
export default tseslint.config(
js.configs.recommended,
...tseslint.configs.recommended,
prettier,
{ rules: { '@typescript-eslint/no-unused-vars': 'warn' } }
)
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 提交被钩子拦住 | lint 有错 | 按提示修或 --no-verify(不推荐) |
| ESLint 与 Prettier 打架 | 没关 ESLint 格式规则 | 加 eslint-config-prettier |
面试考法:问 ESLint 与 Prettier 分工。答到:ESLint 管质量与潜在 bug,Prettier 管格式,别让 ESLint 管格式。
5.4 pnpm workspace monorepo
为什么需要它:多个项目共享组件库、工具函数、类型定义时,复制粘贴会导致版本漂移。monorepo 把所有包放一个仓库统一管理。
核心机制:
- 根
pnpm-workspace.yaml声明包目录:packages: ['apps/*', 'packages/*']。 - 内部包用
workspace:*引用,如"@ann/utils": "workspace:*";发布前改成版本号。 - 包结构:每个包有自己的
package.json、src/index.ts、tsconfig.json;构建产物在dist/。
最小可运行示例:
# pnpm-workspace.yaml
packages:
- 'apps/*'
- 'packages/*'
// packages/utils/package.json
{
"name": "@ann/utils",
"version": "0.0.1",
"type": "module",
"main": "./src/index.ts"
}
// apps/web/package.json(引用内部包)
{
"dependencies": {
"@ann/utils": "workspace:*"
}
}
// apps/web/src/main.ts
import { sum } from '@ann/utils'
console.log(sum(1, 2))
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 找不到内部包 | 没在 workspace 里 | 确认 pnpm-workspace.yaml |
| 改了包源码不生效 | 引用了 dist 缓存 | 直接引用 src 或重启 dev |
面试考法:问 monorepo 的收益与代价。答到:收益是共享代码、统一版本、原子提交;代价是构建配置复杂、仓库变大,需要 Turborepo/Nx 做增量构建(了解)。
5.5 代码分割与懒加载
为什么需要它:首屏只需要当前路由的代码,其它路由按需加载,能显著减小首屏 bundle。
核心机制:
- 路由级懒加载:React
React.lazy+Suspense;Vue 路由组件用动态 import。 - 大组件懒加载:重型图表、编辑器用
React.lazy或 VuedefineAsyncComponent。 - 配合 manualChunks:第三方库独立缓存,路由 chunk 按需加载。
最小可运行示例:
// React 路由懒加载(见 12.4 5.6)
const About = lazy(() => import('./About'))
// 打包后 About 单独一个 chunk,访问 /about 时才下载
// Vue 路由懒加载
routes: [{ path: '/about', component: () => import('./About.vue') }]
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 懒加载白屏 | 没 loading fallback | 包 Suspense |
| 切路由 chunk 404 | 部署后文件名变了 | 确认服务器缓存与 base 配置 |
5.6 产物分析
为什么需要它:不知道 bundle 里有什么,拆包靠猜。用分析工具看每个依赖占多少体积。
核心机制:
vite-bundle-visualizer或rollup-plugin-visualizer生成交互式 treemap。- 看 dist 目录:
index-xxx.js是入口,vendor-xxx.js是第三方,About-xxx.js是懒加载 chunk。 - sourcemap:开发默认开,生产默认关;开了能在错误监控平台还原压缩堆栈。
最小可运行示例:
pnpm add -D vite-bundle-visualizer
pnpm exec vite-bundle-visualizer
# 浏览器打开生成的 treemap
常见坑:
| 现象 | 原因 | 修法 |
|---|---|---|
| 生产 bundle 巨大 | 全量引入了 UI 库或图表 | 改按需引入或拆 chunk |
| sourcemap 泄露源码 | 生产开了 sourcemap 且没限制 | 关掉或上传到错误平台不公开 |
六、分层练习
6.1 复现型
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| 配别名与代理 | @ 指向 src、/api 代理 | 接口跨域通 | 1.5 小时 |
| 配多环境变量 | dev/prod 不同接口地址 | 切换 mode 生效 | 1 小时 |
| 拆 vendor chunk | vue/react 独立 chunk | dist 里有 vendor 文件 | 1.5 小时 |
6.2 改造型
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| 接 ESLint + Prettier | 提交自动格式化 | pre-commit 钩子生效 | 2 小时 |
| 建 monorepo | 两个 app 共享一个 utils 包 | workspace:* 引用通 | 3 小时 |
| 路由懒加载 | 三个路由拆 chunk | 首屏 bundle 减小 | 1.5 小时 |
6.3 设计型
| 练习 | 要求 | 验收标准 | 预计耗时 |
|---|---|---|---|
| 用分析工具拆包 | 找出最大依赖并拆出 | treemap 与首屏体积对比 | 2 小时 |
| 设计内部包结构 | utils 与 ui 两个包 | 类型共享、引用干净 | 2 小时 |
七、排障表
| 现象 | 可能原因 | 排查步骤 | 解决办法 |
|---|---|---|---|
| 别名构建报错 | tsconfig 与 vite 不一致 | 看两边配置 | 同步 paths/alias |
| env 是 undefined | 没 VITE_ 前缀 | 看变量名 | 加前缀 |
| dev 改 env 不生效 | 没重启 | 重启 dev server | 重启 |
| 提交被拦 | lint 有错 | 看输出 | 修错或临时 no-verify |
| 找不到内部包 | workspace 没声明 | 看 pnpm-workspace.yaml | 补声明 |
| 懒加载白屏 | 没 Suspense | 看控制台 | 包 Suspense |
| 切路由 404 | base 或缓存 | 看 Network | 配 base 与服务器 |
| bundle 巨大 | 全量引入 | visualizer 分析 | 按需引入、拆 chunk |
八、出口条件
全部勾选后进入 阶段 6 Node BFF 与 SSR。
- [ ] 能配 Vite 别名、代理、manualChunks
- [ ] 能用 .env 管理多环境变量,知道只有 VITE_ 开头暴露
- [ ] 能接 ESLint + Prettier + husky 提交钩子
- [ ] 能建 pnpm workspace monorepo 并互相引用内部包
- [ ] 能做路由级代码分割并分析 bundle 体积
自测题:
- Vite 开发期与生产期打包方式有什么不同?
- 要点:开发期原生 ESM 不打包,生产期 Rollup 打包。
- 为什么环境变量要 VITE_ 前缀?
- 要点:白名单机制,防止服务端机密打进前端。
- ESLint 与 Prettier 怎么分工?
- 要点:ESLint 管质量,Prettier 管格式。
- pnpm workspace 怎么引用内部包?
- 要点:workspace:*,统一在 pnpm-workspace.yaml 声明。
- 路由懒加载解决什么问题?
- 要点:减小首屏 bundle,按需加载其它路由代码。
- 生产 sourcemap 为什么要谨慎?
- 要点:公开会泄露源码,应上传到错误平台而非公开部署。