npm run dev 能跑但 build 失败怎么办

npm run dev 能跑，不代表项目已经能上线。dev 模式通常更宽松，目标是让你本地开发；build 模式会做更严格的类型检查、lint、静态生成、依赖打包和生产配置校验。所以“本地页面能打开，但 build 失败”是新手很常见的卡点。

先给保守结论：不要把 build 失败当成部署平台的问题。先在本地复现 npm run build，保存完整日志，找出失败阶段，再判断是 TypeScript、lint、环境变量、路径大小写、静态生成、依赖版本，还是部署环境差异。短表可以看 build 失败检查清单，误区复盘看 build 失败常见错误和解决步骤。

适合谁

适合本地 npm run dev 能打开页面，但 npm run build、Vercel 部署、CI 检查失败的新手。你可能正在做 Next.js、React、静态站、小工具页或作品集项目。

也适合准备接“小网站部署前检查”任务的人。客户说“本地能跑，为什么上线失败”，你需要先拆日志和环境差异，而不是直接改一堆文件。

不适合谁

不适合在客户生产项目里直接关掉 TypeScript、关掉 lint、删除环境变量校验或绕过 build 检查的人。build 失败往往是在提醒你生产环境会出问题，不能把检查当成麻烦。

也不适合没有仓库、没有日志、没有验证命令的任务。客户只给一句“build failed”，你最多先问材料，不能承诺修好。

风险提醒

build 失败的风险是“dev 假象”。页面在本地能打开，可能只是因为某条路由没访问、某个组件没渲染、某个环境变量在本地存在、某个大小写路径在 Windows 上没暴露。生产构建会把更多页面和依赖一起检查出来。

如果排查需要登录 Vercel、GitHub、私有仓库、客户环境变量后台、生产数据库或真实 token，先记录为待确认事项。没有授权前，只分析日志和项目文件，不操作客户账号。

具体步骤

1. 保存完整日志。复制 npm run build 的完整输出，不要只保存最后一行。
2. 确认本地复现。先在项目根目录运行 build，不要只看部署平台截图。
3. 找失败阶段。看是 TypeScript、lint、静态生成、依赖安装、图片处理、路由生成，还是环境变量校验。
4. 检查环境变量。确认 build 需要哪些变量，哪些可以为空，哪些必须由客户确认。
5. 检查路径大小写。Windows 本地可能不敏感，Linux 部署环境可能敏感。
6. 检查动态代码。静态生成时访问浏览器对象、读取不存在的数据、调用未授权接口，都可能失败。
7. 修复后运行验证。至少跑 build，必要时再跑 lint、test 和关键页面检查。

dev 和 build 有什么区别

dev 模式强调开发速度，很多问题只有访问到某个页面或组件时才出现。build 模式强调生产产物，会提前检查更多路径和类型，并把页面生成、服务端代码、客户端代码和依赖打包放到一起验证。

所以不要说“dev 能跑，说明代码没问题”。更准确的说法是“dev 只证明本地开发服务器能启动，并不能证明生产构建通过”。这个区别是项目沟通里很重要的一句。

常见原因

第一类是类型错误。TypeScript 在 build 阶段更严格，未处理的 undefined、错误 props、导入类型不匹配都会暴露。第二类是 lint 或格式规则。第三类是环境变量缺失，尤其是部署平台里没有配置本地 .env 里的变量。

第四类是静态生成错误，比如页面在 build 时调用了运行时才有的数据。第五类是路径大小写问题，比如导入 Button 但文件叫 button。第六类是依赖版本差异，尤其是锁文件、Node 版本和包管理器不一致。

项目前怎么处理

先把任务定义为“build 失败诊断”。交付内容可以是失败阶段、可能原因、低风险修复建议和客户待确认事项。只有当日志完整、仓库可访问、验证命令明确、授权清楚时，才进入修复。

需要客户沟通稿时，可以用 Proposal 生成器 起草问题；需要估算诊断和验证时间时，用 报价计算器。

CTA：下一步

在项目根目录运行 npm run build，保存完整日志。然后把失败阶段、报错文件、环境变量、Node 版本、包管理器和验证命令写下来。遇到日志看不懂时，用 报错解释器 先拆原因。

免责声明

本文是学习和排查流程，不构成法律、财务、安全或职业承诺。实际修复需要结合项目框架、真实日志、部署环境、客户授权和验证结果人工判断。