React / 系统课时

排查常见故障

排查常见故障

Next.js 故障排查的关键不是反复改代码,而是先确定错误发生在哪一层,再用构建输出、HTTP 状态、缓存现象和数据库证据逐层缩小范围。本篇给出一条可复用的定位顺序,覆盖构建失败、缓存异常、接口错误和数据库连接问题。

学习目标

  • 能先复现故障并保留最有价值的原始证据
  • 能把问题快速分到构建、缓存、接口或数据库连接层
  • 能在修复后用同一组检查验证问题确实消失

先固定复现条件

先记录故障发生在哪个环境、使用哪个提交、Node.js 与包管理器版本,以及是否只在部署平台出现。不要一开始就删除缓存、升级依赖或重装所有包,这些动作会改变现场,让真正的根因更难复现。

对构建问题,第一步是在项目根目录执行生产构建,并保留最早出现的确定性错误。下面的命令额外打印退出码,便于在本地和 CI 中采用同一判断标准。

bash
npm run build
printf 'build_exit=%s\n' "$?"

预期输出:构建成功时,中间日志会因 Next.js 版本和项目内容不同而变化,但最后一行应为:

text
build_exit=0

如果最后是非零值,就从第一条编译、类型、模块解析或配置错误开始处理,不要只盯着最后的通用失败提示。若本地成功而部署失败,优先比较 Node.js 版本、锁文件、环境变量、工作目录和构建命令是否一致。

用证据把故障分流

一个页面报错可能同时经过路由、缓存、接口和数据库。最省时间的做法是先找到“最后一个正常点”和“第一个异常点”,而不是从 UI 一路猜到底。

Next.js 常见故障的证据分流

现象 第一证据 常见根因方向
npm run build 失败 第一条明确错误 导入路径、类型错误、缺失配置、环境差异
数据已变但页面仍旧 直接数据源与页面结果对比 缓存未失效、失效范围不对、客户端仍持有旧路由数据
接口调用失败 HTTP 状态码与服务端日志 请求格式、鉴权、业务异常、未捕获异常
数据库偶发或持续不可用 连接错误类型与运行环境 凭据、网络/TLS、连接数、运行时兼容性

区分缓存异常与接口错误

怀疑缓存时,先确认数据库或上游 API 的源数据是否已经更新。若源数据是新的、直接调用接口也是新的,但页面仍显示旧值,问题才更可能位于缓存或客户端路由状态。数据写入后应按项目的缓存策略使用 revalidatePath 或 revalidateTag 等失效手段;本地删除 .next 只能重建本地构建产物,不能替代生产环境中的正确失效逻辑。

接口问题要先看状态码,再看响应体和同一时间点的服务端日志。下面的命令不会假设接口一定返回 JSON,适合先确认真实状态。将 <PORT> 和 <PATH> 替换为当前项目实际值。

bash
curl -sS -o /tmp/next-response.txt -w 'status=%{http_code}\n' "http://localhost:<PORT>/<PATH>"
cat /tmp/next-response.txt

预期输出:

text
status=<STATUS>
<RESPONSE_BODY>

4xx 通常应沿请求参数、身份与权限、资源是否存在继续查;5xx 则优先看 Route Handler、Server Action 或服务端渲染日志中的异常。不要把所有错误统一改成 200,否则监控和调用方都会失去判断依据。

定位数据库连接问题

数据库错误先分成四类:配置不存在、认证失败、网络或 TLS 超时、连接池耗尽。第一步只检查连接变量“是否存在”,不要把完整连接串打印到终端或日志。以下示例假设项目使用常见的 DATABASE_URL 变量。

bash
node -e "console.log('DATABASE_URL configured =', Boolean(process.env.DATABASE_URL))"

预期输出:

text
DATABASE_URL configured = true

如果这里是 false,先修复当前运行环境的变量注入;如果是 true 但仍连接失败,再根据数据库客户端抛出的错误区分用户名密码、DNS、端口、防火墙、证书或连接数问题。对于只在部署环境出现的故障,还要确认变量属于正确的环境,并检查数据库驱动是否适用于当前服务器运行时。

修复后怎样验收

修复完成后,用与定位阶段相同的路径重新验证:生产构建退出码应恢复为 0;受影响接口应返回预期状态;数据库操作不再出现连接类错误;修改数据后,目标页面应在设计的失效时机读取到新值。若只验证“页面现在能打开”,却没有重跑构建、接口和数据链路,问题很容易在下一次部署时重新出现。

真正可靠的排障记录应留下“现象、证据、根因、最小修复、验证结果”五项。这样下一次遇到相似故障时,可以从已有证据直接判断层级,而不是重复从清缓存或重装依赖开始碰运气。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

排查常见故障

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通