npm run dev 能跑但 build 失败？7 个最常见原因和修复

npm run dev 一切正常，npm run build 却一堆红字——这不是玄学。dev 是宽松的开发模式，build 是严格的生产编译，两者的校验强度和运行环境不一样。dev 帮你跑起来，build 帮你抓出真正会上线出问题的代码。

先看 build 日志里第一条报错，再按下面对号入座。

为什么 dev 过、build 不过

• dev 用增量编译、不做完整类型检查、不跑生产优化；
• build 会做全量 TypeScript 类型检查、ESLint、Tree-shaking、SSR 预渲染，任何一步出错就整体失败。

所以 build 失败基本是 4 个方向：类型/lint、SSR 预渲染、环境差异、依赖位置。

① TypeScript 类型错误（dev 不拦，build 拦）

成因：dev 默认不阻断类型错误，但 next build / tsc 会把类型错当成失败。

修复：本地先单独跑类型检查，把红字一次看全：

npx tsc --noEmit

按报错逐个改；临时绕过可在该行上面加 // @ts-expect-error 并写原因，但别滥用。

② ESLint 错误被当成 build 失败

成因：项目配置了 build 时跑 lint，未使用变量、缺 key、依赖数组不全等被当错误。

修复：本地跑 npm run lint 看具体规则；该修的修。确实要先上线，可在 next.config 里临时 eslint: { ignoreDuringBuilds: true }，但这是欠债不是解决。

③ SSR 里用了 window / document / localStorage

成因：build 要在 Node 环境预渲染页面，那里没有 window，于是报 window is not defined / document is not defined。

修复：把访问浏览器 API 的代码挪进 useEffect（只在客户端跑），或动态导入禁用 SSR：

import dynamic from "next/dynamic";
const Chart = dynamic(() => import("./Chart"), { ssr: false });

④ 环境变量 build 时缺失

成因：本地 .env 有的变量，CI / 构建环境没有；或前端要用的变量没加 NEXT_PUBLIC_ 前缀，build 后变 undefined。

修复：在构建平台（Vercel / CI）补齐环境变量；浏览器要读的变量必须 NEXT_PUBLIC_ 开头；别把变量写死进代码。

⑤ import 路径大小写（本地不敏感，Linux 敏感）

成因：macOS / Windows 文件系统不区分大小写，本地 import './Header' 能找到 header.tsx；CI 的 Linux 区分，直接 Module not found。

修复：核对每个 import 的大小写和真实文件名完全一致。这条在本地几乎无法复现，要特别留意。

⑥ 依赖装在 devDependencies，生产构建装不到

成因：构建时需要的包被 --save-dev 装进了 devDependencies，生产安装（npm ci --omit=dev）装不到。

修复：构建/运行时需要的包放进 dependencies：

npm install <包名> --save

⑦ 动态导入 / 未使用变量在严格模式报错

成因：生产编译开严格模式后，未使用的 import、不可达代码、错误的动态导入路径会被标记为错误。

修复：按报错删未使用代码；动态导入的路径不能是完全动态的变量，保留可分析的字符串前缀。

一招稳定复现：用干净环境本地 build

别信本地缓存，把环境清干净再 build，复现出和线上一样的报错：

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

本地和构建平台的 Node 版本也要一致（node -v 对齐）。

让 Codex 辅助定位

这是我的 npm run build 报错日志：[贴完整日志]
我本地 npm run dev 正常。请判断属于类型 / lint / SSR / 环境变量 / 依赖 哪一类，
指出关键报错行，先给只读验证步骤，不要直接改我的 next.config 或 tsconfig。

风险提醒

• 用 ignoreBuildErrors / ignoreDuringBuilds 强行让 build 过，是把问题推到线上，能修就别用。
• 改 tsconfig、next.config、依赖文件前先有 Git 记录，方便回滚。

相关工具

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

相关报错排查

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

• npm install 报错怎么解决
• Cannot find module 报错怎么解决
• .env 环境变量不生效怎么解决
• Node 版本不匹配怎么解决

免责声明

本文成因与修复对应 TypeScript / Next.js / Node 构建的通用行为，供学习和排查参考；具体项目涉及客户代码、生产部署时需明确授权并人工复核。