前端工程化 / 系统课时

排查仅生产构建失败

排查仅生产构建失败

本课给出“先分阶段、再做二分”的构建排查方法,帮助你定位开发环境正常、但 vite build、本地预览或线上部署失败的问题,并覆盖动态导入、环境变量、Tree Shaking、压缩和插件差异。

学习目标

  • 能区分构建期、预览运行期与部署期故障。
  • 能通过诊断配置逐步关闭变量,缩小问题范围。
  • 能识别生产链路中常见的动态导入、环境变量和插件边界。

先确定失败发生在哪一阶段

不要把“生产失败”当成一个问题。先依次执行构建与本地预览:构建命令失败说明问题位于转换、打包或插件钩子;构建成功但预览报错,通常是运行时代码、资源路径或环境变量;本地预览正常而线上失败,则优先检查部署基路径、静态服务器回退、缓存和网关配置。

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

预期输出

text
✓ built in <TIME>
➜  Local:   http://127.0.0.1:4173/

具体日志格式会随 Vite 版本和包管理器不同而变化,但应看到构建完成和本地预览地址。若第一条命令已经失败,不要继续从浏览器现象猜测,应先保留完整堆栈和首个报错位置。

对比开发与构建转换链

开发服务器按请求即时转换模块,很多未被访问的代码不会立刻执行;生产构建会遍历依赖图、处理静态资源、执行 Tree Shaking、生成分块,并可能压缩代码。插件还可以通过 apply、enforce 或不同钩子只参与其中一条链路。

Vite 开发与生产构建转换链对比

因此,排查时应围绕“生产链路新增了什么”展开,而不是反复修改业务代码。最常见的增量包括:完整依赖遍历、静态替换的环境变量、分块边界、无用代码删除、压缩重命名,以及仅在 build 阶段执行的插件。

建立可回退的诊断构建

创建临时诊断配置,先打开 Source Map 并关闭压缩。这样可以判断故障是否由压缩触发,同时让浏览器堆栈映射回源码。不要直接覆盖正式配置,避免排查参数误入发布流程。

ts
import { defineConfig } from 'vite'

export default defineConfig(({ command, mode }) => {
  console.log(`[vite-context] command=${command} mode=${mode}`)

  return {
    build: {
      sourcemap: true,
      minify: false,
    },
  }
})

将其保存为 vite.diagnose.config.ts 后执行:

bash
npx vite build --config vite.diagnose.config.ts

预期输出

text
[vite-context] command=build mode=production
✓ built in <TIME>

若诊断构建成功而正式构建失败,逐项恢复压缩、插件和自定义 Rollup 选项,每次只恢复一项。若诊断构建仍失败,优先处理首个解析错误、插件异常或无法解析的导入。

检查动态导入与环境变量

动态导入的路径必须能在构建期推导。把任意字符串直接拼进 import(),开发时可能因刚好未访问而隐藏问题,生产构建却无法可靠生成分块。可将候选模块显式收集,再按键选择加载器。

下面是依赖 Vite 模块环境的片段示例,假设页面模块位于 src/pages:

ts
const pageModules = import.meta.glob('./pages/*.ts')

export async function loadPage(name: string) {
  const loader = pageModules[`./pages/${name}.ts`]

  if (!loader) {
    throw new Error(`Unknown page: ${name}`)
  }

  return loader()
}

验证时应同时测试合法页面名和不存在的页面名,确认前者生成并加载对应分块,后者返回可控错误,而不是在运行时出现 404。

环境变量只应通过明确的字面量属性读取,例如 import.meta.env.VITE_API_BASE。客户端可见变量需要符合项目约定的公开前缀;密钥不应写入前端环境变量。构建前打印“变量是否存在”即可,不要输出密钥值,并确认所用 mode 与对应的 .env 文件一致。

排查 Tree Shaking、压缩与插件差异

若仅在启用 Tree Shaking 后出错,检查代码是否依赖未显式导出的全局注册、副作用导入,或第三方包是否错误声明 sideEffects: false。修复方向是显式导入并调用初始化函数,或更正包的副作用声明,而不是用无关引用强行“保活”。

若只在压缩后出错,重点排查对 function.name、class.name、变量名或源码文本的依赖。业务逻辑不应把可被重命名的标识符当作稳定协议;应改用显式常量、枚举值或配置键。

插件问题要检查三点:插件是否只设置了 apply: 'serve',生产所需转换是否遗漏;多个插件的 enforce 和数组顺序是否改变了输入;build 钩子是否读取了只在开发时存在的文件或服务。临时禁用插件时每次只移除一个,并记录构建结果。

失败特征 优先检查
构建时报无法解析动态导入 import() 路径是否可静态推导
预览时报配置值为 undefined mode、变量前缀与字面量读取
关闭压缩后恢复 是否依赖函数名、类名或变量名
禁用某插件后恢复 apply、enforce、钩子和插件顺序
某初始化逻辑在产物中消失 副作用导入与 sideEffects 声明

用产物验证而不是只看构建成功

构建成功只说明生成了文件,不代表功能正确。至少用 vite preview 验证首页直达、刷新路由、动态页面加载、关键接口地址和静态资源路径。浏览器报错时应使用 Source Map 定位源码,并检查 Network 面板中的 404、分块加载失败和缓存命中情况。

修复后恢复正式压缩与插件配置,再完整构建一次。只有正式构建、本地预览和目标部署环境都通过,才算完成闭环。

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

目录与阅读设置

阅读设置

17

记录一个想法

排查仅生产构建失败

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

登录哪都通