Vue / 系统课时
配置生产构建
配置生产构建
本课把开发态项目收敛为可部署的生产产物:区分生产环境变量,校准子路径资源地址,控制源码映射与代码分包,并用构建分析和本地预览验证 dist 目录是否可交付。
学习目标
- 配置仅在生产构建中生效的环境变量和公共资源路径。
- 控制源码映射、代码分包与构建分析文件的生成方式。
- 通过脚本检查产物结构,并在本地预览生产版本。
明确生产构建边界
生产构建不是简单地执行一次压缩。它需要同时确定四件事:应用最终挂载在哪个 URL 前缀下、哪些变量允许进入浏览器、是否生成源码映射,以及如何拆分体积较大的依赖。开发服务器能正常运行,并不能证明这些配置在静态服务器上也正确。
Vite 只会把指定前缀的环境变量暴露给前端代码。下面使用 VITE_ 前缀,并让应用部署在 /admin/ 子路径;源码映射默认关闭,需要接入错误监控平台时再改为 hidden。
# .env.production
VITE_PUBLIC_BASE=/admin/
VITE_SOURCEMAP=false这两个变量会在 vite build --mode production 时加载。不要把数据库密码、私钥或后端管理令牌写入任何 VITE_ 变量,因为它们会进入浏览器可下载的 JavaScript 文件。

先安装构建分析和跨平台环境变量工具。命令最后输出固定标记,便于在终端或流水线中确认安装步骤成功。
npm install --save-dev rollup-plugin-visualizer cross-env && echo "DEPENDENCIES_OK"预期输出的关键末行如下,前面的包数量和审计信息会随锁文件变化。
DEPENDENCIES_OK然后在 package.json 中保留以下脚本。这里是片段示例,需要合并到现有 scripts,不能覆盖项目原有命令。
{
"scripts": {
"build": "vue-tsc -b && vite build",
"build:analyze": "cross-env ANALYZE=true npm run build",
"preview": "vite preview"
}
}vite.config.ts 负责统一资源前缀、源码映射和依赖分包。分析插件只在 ANALYZE=true 时启用,避免普通构建额外生成报告。
import { defineConfig, loadEnv } from 'vite'
import vue from '@vitejs/plugin-vue'
import { visualizer } from 'rollup-plugin-visualizer'
function normalizeBase(value: string): string {
const withLeadingSlash = value.startsWith('/') ? value : `/${value}`
return withLeadingSlash.endsWith('/') ? withLeadingSlash : `${withLeadingSlash}/`
}
export default defineConfig(({ mode }) => {
const env = loadEnv(mode, process.cwd(), 'VITE_')
const analyze = process.env.ANALYZE === 'true'
return {
base: normalizeBase(env.VITE_PUBLIC_BASE || '/'),
plugins: [
vue(),
...(analyze
? [visualizer({ filename: 'dist/stats.html', gzipSize: true, brotliSize: true })]
: [])
],
build: {
outDir: 'dist',
emptyOutDir: true,
sourcemap: env.VITE_SOURCEMAP === 'hidden' ? 'hidden' : false,
rollupOptions: {
output: {
manualChunks(id) {
if (!id.includes('node_modules')) return undefined
if (/node_modules[\\/](vue|vue-router|pinia)[\\/]/.test(id)) {
return 'vue-vendor'
}
return 'vendor'
}
}
}
}
}
})hidden 源码映射会生成 .map 文件,但不会在 JavaScript 尾部写入公开引用,适合由部署流程单独上传到错误监控平台。若没有对应平台,保持关闭可以减少泄露源码结构和增加产物体积的风险。
构建、分析与运行验证
先执行标准构建,并用 Node.js 检查关键目录。命令会在构建失败、类型检查失败或关键产物缺失时返回非零退出码。
npm run build && node -e "const fs=require('node:fs'); const required=['dist/index.html','dist/assets']; const missing=required.filter((p)=>!fs.existsSync(p)); if(missing.length){console.error('MISSING:'+missing.join(',')); process.exit(1)} console.log('BUILD_OK')"预期输出的关键末行如下,前面的文件体积和耗时会因项目而异。
BUILD_OK需要定位包体积来源时执行分析构建。报告只用于研发检查,不应随静态资源一起发布。
npm run build:analyze && node -e "const fs=require('node:fs'); if(!fs.existsSync('dist/stats.html')) process.exit(1); console.log('ANALYZE_OK')"预期输出的关键末行如下。
ANALYZE_OK完成分析后重新执行一次 npm run build,因为标准构建会先清空 dist,从而移除 stats.html。随后启动本地预览,并访问 http://127.0.0.1:4173/admin/。
npm run preview -- --host 127.0.0.1 --port 4173预期输出包含以下地址,实际启动耗时可能不同。
Local: http://127.0.0.1:4173/admin/交付前检查与常见问题
交付前至少检查首页、刷新后的深层路由、登录跳转和一次真实接口请求。浏览器网络面板中的脚本与样式地址都应以 /admin/assets/ 开头,且不能出现开发地址或本机端口。
| 现象 | 优先检查 | 修复方向 |
|---|---|---|
| 首页空白且资源 404 | base 与部署 URL 是否一致 |
统一为 /admin/,重新构建 |
| 构建成功但类型错误未拦截 | build 是否先执行 vue-tsc -b |
不要只运行 vite build |
| 主包仍然过大 | stats.html 中的依赖占比 |
按业务路由懒加载,谨慎调整分包 |
| 线上可直接下载源码映射 | VITE_SOURCEMAP 是否误设 |
关闭或改用 hidden,由监控平台托管 |
不要只比较压缩前体积。浏览器实际下载量更接近 gzip 或 Brotli 指标,同时还要关注首屏必须加载的块数;拆分过细会增加请求和执行开销。