前端工程化 / 系统课时
排查仅生产构建失败
排查仅生产构建失败
本课给出“先分阶段、再做二分”的构建排查方法,帮助你定位开发环境正常、但 vite build、本地预览或线上部署失败的问题,并覆盖动态导入、环境变量、Tree Shaking、压缩和插件差异。
学习目标
- 能区分构建期、预览运行期与部署期故障。
- 能通过诊断配置逐步关闭变量,缩小问题范围。
- 能识别生产链路中常见的动态导入、环境变量和插件边界。
先确定失败发生在哪一阶段
不要把“生产失败”当成一个问题。先依次执行构建与本地预览:构建命令失败说明问题位于转换、打包或插件钩子;构建成功但预览报错,通常是运行时代码、资源路径或环境变量;本地预览正常而线上失败,则优先检查部署基路径、静态服务器回退、缓存和网关配置。
npm run build
npm run preview -- --host 127.0.0.1 --port 4173预期输出
✓ built in <TIME>
➜ Local: http://127.0.0.1:4173/具体日志格式会随 Vite 版本和包管理器不同而变化,但应看到构建完成和本地预览地址。若第一条命令已经失败,不要继续从浏览器现象猜测,应先保留完整堆栈和首个报错位置。
对比开发与构建转换链
开发服务器按请求即时转换模块,很多未被访问的代码不会立刻执行;生产构建会遍历依赖图、处理静态资源、执行 Tree Shaking、生成分块,并可能压缩代码。插件还可以通过 apply、enforce 或不同钩子只参与其中一条链路。

因此,排查时应围绕“生产链路新增了什么”展开,而不是反复修改业务代码。最常见的增量包括:完整依赖遍历、静态替换的环境变量、分块边界、无用代码删除、压缩重命名,以及仅在 build 阶段执行的插件。
建立可回退的诊断构建
创建临时诊断配置,先打开 Source Map 并关闭压缩。这样可以判断故障是否由压缩触发,同时让浏览器堆栈映射回源码。不要直接覆盖正式配置,避免排查参数误入发布流程。
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 后执行:
npx vite build --config vite.diagnose.config.ts预期输出
[vite-context] command=build mode=production
✓ built in <TIME>若诊断构建成功而正式构建失败,逐项恢复压缩、插件和自定义 Rollup 选项,每次只恢复一项。若诊断构建仍失败,优先处理首个解析错误、插件异常或无法解析的导入。
检查动态导入与环境变量
动态导入的路径必须能在构建期推导。把任意字符串直接拼进 import(),开发时可能因刚好未访问而隐藏问题,生产构建却无法可靠生成分块。可将候选模块显式收集,再按键选择加载器。
下面是依赖 Vite 模块环境的片段示例,假设页面模块位于 src/pages:
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、分块加载失败和缓存命中情况。
修复后恢复正式压缩与插件配置,再完整构建一次。只有正式构建、本地预览和目标部署环境都通过,才算完成闭环。