React / 系统课时
排查常见故障
排查常见故障
Next.js 故障排查的关键不是反复改代码,而是先确定错误发生在哪一层,再用构建输出、HTTP 状态、缓存现象和数据库证据逐层缩小范围。本篇给出一条可复用的定位顺序,覆盖构建失败、缓存异常、接口错误和数据库连接问题。
学习目标
- 能先复现故障并保留最有价值的原始证据
- 能把问题快速分到构建、缓存、接口或数据库连接层
- 能在修复后用同一组检查验证问题确实消失
先固定复现条件
先记录故障发生在哪个环境、使用哪个提交、Node.js 与包管理器版本,以及是否只在部署平台出现。不要一开始就删除缓存、升级依赖或重装所有包,这些动作会改变现场,让真正的根因更难复现。
对构建问题,第一步是在项目根目录执行生产构建,并保留最早出现的确定性错误。下面的命令额外打印退出码,便于在本地和 CI 中采用同一判断标准。
npm run build
printf 'build_exit=%s\n' "$?"预期输出:构建成功时,中间日志会因 Next.js 版本和项目内容不同而变化,但最后一行应为:
build_exit=0如果最后是非零值,就从第一条编译、类型、模块解析或配置错误开始处理,不要只盯着最后的通用失败提示。若本地成功而部署失败,优先比较 Node.js 版本、锁文件、环境变量、工作目录和构建命令是否一致。
用证据把故障分流
一个页面报错可能同时经过路由、缓存、接口和数据库。最省时间的做法是先找到“最后一个正常点”和“第一个异常点”,而不是从 UI 一路猜到底。

| 现象 | 第一证据 | 常见根因方向 |
|---|---|---|
npm run build 失败 |
第一条明确错误 | 导入路径、类型错误、缺失配置、环境差异 |
| 数据已变但页面仍旧 | 直接数据源与页面结果对比 | 缓存未失效、失效范围不对、客户端仍持有旧路由数据 |
| 接口调用失败 | HTTP 状态码与服务端日志 | 请求格式、鉴权、业务异常、未捕获异常 |
| 数据库偶发或持续不可用 | 连接错误类型与运行环境 | 凭据、网络/TLS、连接数、运行时兼容性 |
区分缓存异常与接口错误
怀疑缓存时,先确认数据库或上游 API 的源数据是否已经更新。若源数据是新的、直接调用接口也是新的,但页面仍显示旧值,问题才更可能位于缓存或客户端路由状态。数据写入后应按项目的缓存策略使用 revalidatePath 或 revalidateTag 等失效手段;本地删除 .next 只能重建本地构建产物,不能替代生产环境中的正确失效逻辑。
接口问题要先看状态码,再看响应体和同一时间点的服务端日志。下面的命令不会假设接口一定返回 JSON,适合先确认真实状态。将 <PORT> 和 <PATH> 替换为当前项目实际值。
curl -sS -o /tmp/next-response.txt -w 'status=%{http_code}\n' "http://localhost:<PORT>/<PATH>"
cat /tmp/next-response.txt预期输出:
status=<STATUS>
<RESPONSE_BODY>4xx 通常应沿请求参数、身份与权限、资源是否存在继续查;5xx 则优先看 Route Handler、Server Action 或服务端渲染日志中的异常。不要把所有错误统一改成 200,否则监控和调用方都会失去判断依据。
定位数据库连接问题
数据库错误先分成四类:配置不存在、认证失败、网络或 TLS 超时、连接池耗尽。第一步只检查连接变量“是否存在”,不要把完整连接串打印到终端或日志。以下示例假设项目使用常见的 DATABASE_URL 变量。
node -e "console.log('DATABASE_URL configured =', Boolean(process.env.DATABASE_URL))"预期输出:
DATABASE_URL configured = true如果这里是 false,先修复当前运行环境的变量注入;如果是 true 但仍连接失败,再根据数据库客户端抛出的错误区分用户名密码、DNS、端口、防火墙、证书或连接数问题。对于只在部署环境出现的故障,还要确认变量属于正确的环境,并检查数据库驱动是否适用于当前服务器运行时。
修复后怎样验收
修复完成后,用与定位阶段相同的路径重新验证:生产构建退出码应恢复为 0;受影响接口应返回预期状态;数据库操作不再出现连接类错误;修改数据后,目标页面应在设计的失效时机读取到新值。若只验证“页面现在能打开”,却没有重跑构建、接口和数据链路,问题很容易在下一次部署时重新出现。
真正可靠的排障记录应留下“现象、证据、根因、最小修复、验证结果”五项。这样下一次遇到相似故障时,可以从已有证据直接判断层级,而不是重复从清缓存或重装依赖开始碰运气。