npm run dev 能跑但 build 失败常见错误和解决步骤

build 失败最容易被误判。新手常说“本地能打开，为什么还失败”，然后开始删依赖、关规则、改部署平台。真正稳的顺序是先看完整日志，再找失败阶段，再决定是否修改代码、配置或环境。

完整流程见 npm run dev 能跑但 build 失败怎么办，逐项核对见 build 失败检查清单。

适合谁

适合已经多次尝试 build，但每次都只修表面错误的新手。你可能见过 TypeScript 报错、lint 报错、环境变量缺失、静态生成失败或部署平台构建失败。

也适合准备接小网站部署检查任务的人。客户说本地能跑时，你要解释 dev 和 build 的差异，而不是直接承诺上线。

不适合谁

不适合在客户项目里靠关闭检查来交付的人。关闭类型检查或 lint 可能让构建通过，但把问题留到生产环境。

也不适合没有日志、没有仓库、没有验证方式的任务。缺材料时先做诊断问题清单，不要直接报价修复。

风险提醒

build 失败常常暴露生产风险。比如环境变量缺失、动态路由数据为空、静态生成访问了运行时对象、路径大小写在 Linux 上不匹配。这些问题如果被简单绕过，部署后可能出现空白页、接口失败或页面缺数据。

涉及客户账号、部署后台、私有仓库、环境变量、生产数据时，先暂停并记录为待确认事项。没有授权前，不要登录客户平台。

具体步骤

错误一：只相信 dev

dev 能启动只说明开发服务器能工作。它不代表所有页面、类型、静态生成和生产依赖都通过。

更稳做法：每次交付前都跑 build，并保存结果。

错误二：只看最后一行日志

build 日志里真正的原因经常在中间。最后一行可能只是总结失败。

更稳做法：保存完整输出，找第一个明确错误文件和错误类型。

错误三：关掉 TypeScript 或 lint

类型检查和 lint 不是敌人。它们可能正在指出生产风险。

更稳做法：先修具体错误。如果确实需要调整规则，要写明原因和影响。

错误四：忽略环境变量

本地 .env 有变量，不代表部署平台也有。build 阶段需要的变量如果缺失，会直接失败。

更稳做法：列出变量名、用途、是否敏感、由谁配置。客户敏感变量让客户自己确认。

错误五：忽略静态生成

Next.js 等框架可能在 build 时生成页面。此时访问浏览器对象、调用未授权接口、读取空数据都会失败。

更稳做法：确认哪些代码只能在客户端运行，哪些数据需要兜底。

错误六：忽略路径大小写

Windows 本地路径可能不敏感，部署到 Linux 后大小写错误会暴露。

更稳做法：检查 import 路径和实际文件名是否完全一致。

推荐解决顺序

先复现本地 build，再定位失败阶段。然后按类型处理：类型错误先修类型；环境变量先补确认；静态生成先加数据兜底；路径问题先改路径；依赖问题再看包版本。每次只改一个方向，改完跑 build。

如果已经改乱了，先停止新增操作，把尝试过程写成时间线。时间线包括：原始错误、改动动作、验证结果、剩余问题。这样后续更容易接手。

复盘时问自己什么

复盘时先问四个问题。第一，原始错误是否还在记录里。很多人修到一半已经忘记最初失败点，只能继续猜。第二，是否本地复现过 build。只看部署平台截图，容易误判环境问题。第三，是否每次只改一个方向。一次同时改类型、环境变量、依赖和配置，后面很难判断哪一步有效。

第四，是否把客户待确认事项单独列出。比如环境变量值、部署平台权限、私有仓库、第三方 API key，这些不是技术猜测能解决的。它们需要客户确认，而不是你继续试命令。

如果这四个问题有两个以上答不上来，建议先暂停修复，把现有过程整理成诊断记录。能停下来复盘，本身就是避免越修越乱的一步。

CTA：下一步

把当前 build 失败写成六项：完整日志、失败阶段、报错文件、已尝试动作、验证命令、待确认事项。需要模板时去 模板库，需要拆日志时用 报错解释器。

免责声明

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