Next.js 14 上线后接口 504,Server Actions 里 fetch 超时怎么排查

本地正常,上线后固定 60 秒返回 504

Next.js 14 用 standalone 输出部署到 Nginx 后面,页面首屏正常,点提交按钮走 Server ACtion 就一直转圈,第 60 秒整返回 504 Gateway Time-out。这个整数不是随机出现的,说明业务逻辑没崩,而是上游网关等到超时主动断开连接。Nginx 的 proxy_read_timeout 默认就是 60 秒,Node 进程还在等第三方接口返回,浏览器已经先收到了错误页。

同时看两层日志,确认谁先超时

先别急着改配置。在服务器上一边 tail Nginx 错误日志,一边看容器日志,只触发一次请求,对比两边的时间差。如果 Nginx 打出 upstream timed out,说明 Node 侧连响应头都没吐出来;如果容器日志里已经有这次请求的耗时记录,那就是外部接口本身慢,Nginx 只是替它收尾。

grep -c "upstream timed out" /var/log/nginx/error.log
docker logs --since 10m next-app | grep -E "POST|duration"

给 fetch 补上超时,别让请求无限等

Node 里的 fetch 默认没有总时长上限,第三方接口迟迟不返回,连接就一直挂着,直到网关不耐烦。用 AbortSignal.timeout 给它一个 8 秒的截止时间,异常在应用层抛出,能立刻写日志定位;同时在 route handler 里声明 maxDuration,让执行时间超出预算时提前失败,而不是拖到代理层才暴露。

export const maxDuration = 15;

export async function POST(req) {
  const res = await fetch(process.env.API_BASE + "/api/order", {
    method: "POST",
    body: await req.text(),
    signal: AbortSignal.timeout(8000),
  });
  if (!res.ok) return Response.json({ ok: false }, { status: 504 });
  return Response.json(await res.json());
}

三种 504 要分开处理

代理超时的根子通常在上游慢,把 proxy_read_timeout 从 60 秒调到 180 秒只是把它藏得更深;Server Action 里串行调用多个接口,单次 200 毫秒乘上三十次同样会超时,这种情况改成 Promise.all 并发,耗时按最慢的一次算;还有一种是请求体过大,Server Actions 默认只收 1MB,上传文件应该改走 route handler 或直传对象存储。先把耗时按段拆开看,再决定动哪一层,比盲目加时长有效得多。

您可以还会对下面的文章感兴趣: