Vue / 系统课时

配置生产构建

配置生产构建

本课把开发态项目收敛为可部署的生产产物:区分生产环境变量,校准子路径资源地址,控制源码映射与代码分包,并用构建分析和本地预览验证 dist 目录是否可交付。

学习目标

  • 配置仅在生产构建中生效的环境变量和公共资源路径。
  • 控制源码映射、代码分包与构建分析文件的生成方式。
  • 通过脚本检查产物结构,并在本地预览生产版本。

明确生产构建边界

生产构建不是简单地执行一次压缩。它需要同时确定四件事:应用最终挂载在哪个 URL 前缀下、哪些变量允许进入浏览器、是否生成源码映射,以及如何拆分体积较大的依赖。开发服务器能正常运行,并不能证明这些配置在静态服务器上也正确。

Vite 只会把指定前缀的环境变量暴露给前端代码。下面使用 VITE_ 前缀,并让应用部署在 /admin/ 子路径;源码映射默认关闭,需要接入错误监控平台时再改为 hidden。

bash
# .env.production
VITE_PUBLIC_BASE=/admin/
VITE_SOURCEMAP=false

这两个变量会在 vite build --mode production 时加载。不要把数据库密码、私钥或后端管理令牌写入任何 VITE_ 变量,因为它们会进入浏览器可下载的 JavaScript 文件。

生产构建配置与产物流向

先安装构建分析和跨平台环境变量工具。命令最后输出固定标记,便于在终端或流水线中确认安装步骤成功。

bash
npm install --save-dev rollup-plugin-visualizer cross-env && echo "DEPENDENCIES_OK"

预期输出的关键末行如下,前面的包数量和审计信息会随锁文件变化。

text
DEPENDENCIES_OK

然后在 package.json 中保留以下脚本。这里是片段示例,需要合并到现有 scripts,不能覆盖项目原有命令。

json
{
  "scripts": {
    "build": "vue-tsc -b && vite build",
    "build:analyze": "cross-env ANALYZE=true npm run build",
    "preview": "vite preview"
  }
}

vite.config.ts 负责统一资源前缀、源码映射和依赖分包。分析插件只在 ANALYZE=true 时启用,避免普通构建额外生成报告。

ts
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 检查关键目录。命令会在构建失败、类型检查失败或关键产物缺失时返回非零退出码。

bash
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')"

预期输出的关键末行如下,前面的文件体积和耗时会因项目而异。

text
BUILD_OK

需要定位包体积来源时执行分析构建。报告只用于研发检查,不应随静态资源一起发布。

bash
npm run build:analyze && node -e "const fs=require('node:fs'); if(!fs.existsSync('dist/stats.html')) process.exit(1); console.log('ANALYZE_OK')"

预期输出的关键末行如下。

text
ANALYZE_OK

完成分析后重新执行一次 npm run build,因为标准构建会先清空 dist,从而移除 stats.html。随后启动本地预览,并访问 http://127.0.0.1:4173/admin/。

bash
npm run preview -- --host 127.0.0.1 --port 4173

预期输出包含以下地址,实际启动耗时可能不同。

text
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 指标,同时还要关注首屏必须加载的块数;拆分过细会增加请求和执行开销。

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

目录与阅读设置

阅读设置

17

记录一个想法

配置生产构建

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

登录哪都通