npm run dev 能跑但 build 失败检查清单

build 失败排查不要从猜原因开始，要从保存证据开始。完整流程见 npm run dev 能跑但 build 失败怎么办，这篇是可以复制到表格里的检查清单。

适合谁

适合本地页面能打开，但 npm run build、部署平台或 CI 失败的新手。你可以用它检查练习项目、作品集项目或低风险客户小站。

也适合项目前做诊断的人。清单能把“本地没问题”拆成可复查的证据，而不是靠感觉判断。

不适合谁

不适合直接处理客户生产站、支付、认证、企业后台、真实用户数据或无法回滚的部署任务。build 问题可能牵涉生产配置，不应在授权不清时操作。

也不适合客户不提供日志、不提供仓库、不提供验证方式，却要求固定时间修好的任务。材料不够时，先问问题。

风险提醒

不要为了通过 build 就关掉类型检查、lint 或环境变量校验。它们可能正是在阻止生产环境出错。临时绕过检查必须写明风险，并经过确认。

涉及 Vercel、GitHub、私有仓库、环境变量后台、客户 token、生产数据的事项，先写入待确认清单。没有授权前，不要登录或修改。

具体步骤

1. 日志

• 本地 build 命令：
• 完整报错：
• 部署平台报错截图：
• 失败文件：
• 失败阶段：

只保存最后一行通常不够。

2. 环境

• Node 版本：
• 包管理器：
• 操作系统：
• 是否在项目根目录：
• 本地和部署环境是否一致：

本地 dev 能跑，不代表部署环境一样。

3. 类型和 lint

• 是否 TypeScript 报错：
• 是否 ESLint 报错：
• 是否有未处理的 undefined：
• 是否 props 类型不匹配：
• 是否有未使用变量或导入：

不要默认关掉检查。

4. 环境变量

• build 需要哪些变量：
• 本地 .env 是否存在：
• 部署平台是否配置：
• 哪些变量属于客户敏感信息：
• 哪些变量可以用测试值：

客户敏感变量只能由客户确认和配置。

5. 静态生成

• build 时是否访问接口：
• 是否读取浏览器对象：
• 是否依赖运行时数据：
• 是否所有动态路由都有参数：
• 是否有空数据处理：

静态生成错误常常只在 build 时出现。

6. 路径和依赖

• 文件名大小写是否一致：
• 是否混用包管理器：
• 锁文件是否匹配：
• 依赖版本是否变化：
• 图片和静态资源路径是否存在：

Windows 本地正常，不代表 Linux 构建正常。

结论怎么写

结论建议分四类：代码问题、配置问题、环境问题、客户待确认问题。代码问题可以进入修复；配置问题要看是否有权限；环境问题要复现版本差异；客户待确认问题先暂停。

交付记录至少写：失败阶段、原因判断、已检查项目、建议下一步、验证命令。这样客户知道你不是随便试命令。

最低交付记录

最低交付记录建议包含六项。第一项是原始 build 日志，证明问题不是凭感觉判断。第二项是失败阶段，比如 TypeScript、lint、静态生成、环境变量或依赖安装。第三项是报错文件和相关路径。第四项是你已经检查过的内容。第五项是建议修复方向。第六项是客户待确认事项。

如果你还没有修复，只交付诊断也可以，但要写清“目前只完成诊断，尚未修改项目”。如果已经修复，要补上改动文件、验证命令和验证结果。这个记录能避免客户把诊断、修复、部署和线上验收混成一个任务。

做项目时，建议把清单保存为截图或文档。它不是为了显得复杂，而是为了在后续沟通中能说清：哪些问题已经有证据，哪些还需要客户授权或补材料。

本地和部署差异怎么记

如果本地 build 通过但部署失败，另加一组差异记录。先写部署平台使用的 Node 版本、包管理器和安装命令，再写环境变量是否齐全。然后确认部署平台是否运行了额外命令，比如 lint、类型检查、测试或静态导出。

还要记录文件系统差异。Windows 本地对路径大小写不敏感，部署环境可能更严格；本地有缓存，部署环境通常从干净环境安装；本地 .env 存在，部署平台未必配置。把这些差异写出来，排查方向会比“平台有问题”清楚得多。

CTA：下一步

复制这份清单，先填日志、失败阶段、环境变量和验证命令。需要拆报错时用 报错解释器，需要估算诊断时间时用 报价计算器。

免责声明

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