Vercel 部署失败怎么办？8 个常见 build 报错原因和修复

本地 npm run build 能过、推上去 Vercel 却 build 失败，是新手最常踩的坑。原因几乎都写在 Vercel 的 Build Logs 里——别急着重试或改配置，先去 Deployment 页打开完整构建日志，看红色那几行。

下面是 8 个最常见的 Vercel 部署报错、真实成因和修复，最后讲怎么让 Codex 辅助读日志。

第一步：去哪看真正的报错

Vercel 仪表板 → 失败的 Deployment → Build Logs。报错关键句通常是这几类，对号入座往下看：

• Command "npm run build" exited with 1 → 构建命令本身失败（见 ①）
• Module not found / Can't resolve → 找不到模块（见 ②）
• Environment Variable ... references Secret which does not exist / 运行时 undefined → 环境变量（见 ③）
• No Output Directory named "public"/"dist" found → 输出目录配错（见 ④）
• Found invalid Node.js Version / engine → Node 版本（见 ⑤）
• Error: The build exceeded the maximum allowed runtime → 构建超时（见 ⑥）
• 部署成功但访问 404: NOT_FOUND → 路由/输出（见 ⑦）
• 500 / FUNCTION_INVOCATION_FAILED → 运行时函数报错（见 ⑧）

① Command "npm run build" exited with 1（构建命令失败）

成因：本地有缓存或没开严格校验，线上干净环境把警告当错误（最常见是 TypeScript 类型错、ESLint 错、缺依赖）。

修复：用干净环境本地复现，别信增量缓存：

rm -rf node_modules .next && npm ci && npm run build

本地复现出同样的红字，按那条错误改；线上和本地 Node 版本要一致（见 ⑤）。

② Module not found / Can't resolve（找不到模块）

成因：两个高频原因——(a) 大小写：本地 macOS/Windows 不区分大小写，Vercel 的 Linux 区分，import './Header' 实际文件叫 header.tsx 就会挂；(b) 依赖装到了 devDependencies，生产构建装不到。

修复：核对 import 路径大小写和真实文件名完全一致；构建需要的包放进 dependencies：

npm install <包名> --save        # 进 dependencies,不是 --save-dev

③ 环境变量缺失（references Secret / undefined）

成因：本地 .env 有的变量，Vercel 项目里没配；或前端要用的变量没加 NEXT_PUBLIC_ 前缀。

修复：Vercel → Settings → Environment Variables 补齐，勾对 Production 环境，然后重新部署（加完变量不会自动生效，必须 redeploy）。前端可读的变量必须以 NEXT_PUBLIC_ 开头。

④ No Output Directory named "public"/"dist" found（输出目录配错）

成因：Vercel 的 Framework Preset 或 Output Directory 和你项目实际产物目录对不上（Vite 是 dist，CRA 是 build，Next.js 自动识别）。

修复：Settings → Build & Development Settings，把 Framework Preset 选对，或手动把 Output Directory 改成项目真实的产物目录。

⑤ Found invalid Node.js Version（Node 版本不符）

成因：项目 package.json 的 engines.node 或依赖要求的 Node 版本，和 Vercel 默认版本不一致。

修复：在 Settings → Node.js Version 选和本地一致的 LTS 版本；或在 package.json 写明：

"engines": { "node": "20.x" }

⑥ The build exceeded the maximum allowed runtime（构建超时）

成因：依赖过多、生成页面过多（比如几千个静态页）、或构建脚本里有死循环、超大数据处理。

修复：减少构建期的重活；把超大数据生成挪到运行时或增量生成；精简页面数量（页太多本身也拖累收录）。

⑦ 部署成功但 404: NOT_FOUND（访问页面 404）

成因：构建过了但路由对不上——basePath 配错、SPA 没配 rewrites、或输出目录里根本没有那个页面。

修复：Next.js 确认页面文件在正确的 app/ 或 pages/ 路径；纯前端 SPA 在 vercel.json 加 rewrites 把所有路由指向 index.html。

⑧ 500 / FUNCTION_INVOCATION_FAILED（运行时函数报错）

成因：构建成功，但 serverless 函数运行时崩了——常见是运行时读不到环境变量、用了 Node 不支持的 API、或没处理异步异常。

修复：去 Vercel → 该 Deployment → Runtime Logs（不是 Build Logs）看运行时报错；按那条 stack trace 修，重点查 ③ 环境变量和未捕获的 async 异常。

让 Codex 辅助读部署日志

把完整 Build/Runtime 日志贴给 Codex，让它定位而不是盲改：

这是我的 Vercel 部署日志：[贴完整日志]
请判断是 build 阶段还是 runtime 阶段失败、指出关键报错行和最可能原因，
先给只读的验证步骤，不要直接改我的 vercel.json 或环境变量。

可以复制的诊断记录

Vercel 部署失败诊断记录
失败阶段（Build / Runtime）：
关键报错行：
本地 npm ci && npm run build 是否复现：
本地 Node 版本 / Vercel Node 版本：
缺失的环境变量：
Framework Preset / Output Directory：
下一步：

风险提醒

• 别把含密钥的 .env 提交进仓库；环境变量在 Vercel 后台配，别写进代码。
• 客户项目的生产部署、域名、环境变量改动，先确认授权再动。

相关工具

• 报错解释器：贴部署日志自动归类报错
• Codex 工具页
• 项目报价助手

相关报错排查

同一套排查思路的常见报错，建议一起看：

• npm run dev 能跑但 build 失败
• .env 环境变量不生效怎么解决
• Node 版本不匹配怎么解决

免责声明

本文中的报错信息与修复对应 Vercel 官方部署行为，供学习和排查参考；具体项目涉及客户域名、环境变量、生产部署时，需明确授权并人工复核。