Nuxt3升级后出现unhandledRejection: write ECONNABORTED

Question

升级至Nuxt 3后，部分用户在高并发或长时间运行的SSR请求场景下频繁遇到 `unhandledRejection: write ECONNABORTED` 错误。该问题通常出现在服务端渲染过程中，当Node.js服务器向客户端写入响应时连接已被客户端提前终止（如页面刷新、网络中断或超时），导致底层TCP连接中断而触发ECONNABORTED错误。由于Nuxt 3默认未对这类系统级Promise拒绝进行显式捕获，进而抛出未处理的拒绝异常，影响服务稳定性。此问题在使用原生fetch或第三方API调用频繁的场景中尤为明显，需通过全局异常监听与请求生命周期管理来缓解。

Answer 1

1. 问题背景与现象描述

在将项目从 Nuxt 2 升级至 Nuxt 3 后，部分用户反馈在高并发或长时间运行的 SSR（服务端渲染）请求场景下频繁出现 unhandledRejection: write ECONNABORTED 错误。该错误属于 Node.js 底层 TCP 层的系统级异常，通常发生在服务器尝试向客户端写入响应时，发现连接已被客户端主动关闭。

典型触发场景包括：

• 用户快速刷新页面，导致前一个 SSR 请求尚未完成即被中断
• 移动端网络不稳定，连接中途断开
• 反向代理（如 Nginx）设置了较短的超时时间
• 浏览器标签页关闭或跳转

由于 Nuxt 3 基于 Nitro 引擎构建，其内部大量使用 Promise 处理异步逻辑，而此类连接中断事件会以 Promise 拒绝的形式抛出，若未被显式捕获，则触发全局 unhandledRejection 事件，影响服务稳定性。

2. 根本原因分析

通过日志追踪和源码调试，可确认该问题源于 Node.js HTTP 模块在写入响应体时检测到 socket 已关闭。以下是典型的调用链路：

1. Nuxt 3 服务端执行 useFetch 或原生 fetch 发起 API 请求
2. 等待后端数据返回期间，客户端终止连接（如刷新）
3. Node.js 在 res.write() 或 res.end() 时抛出 ECONNABORTED
4. 该错误作为 Promise rejection 抛出，但未被捕获
5. 触发 process.on('unhandledRejection')

值得注意的是，这类错误本质上是“客户端行为引发的服务端异常”，不应视为应用逻辑错误，但因缺乏统一处理机制，容易造成日志污染甚至进程崩溃。

3. 影响范围与风险评估

维度	影响说明
服务稳定性	频繁的 unhandledRejection 可能导致 PM2 或 Docker 容器重启
日志可读性	大量 ECONNABORTED 日志淹没关键业务错误
监控告警	可能误触发异常率阈值告警
资源泄漏	未清理的异步任务可能导致内存堆积
用户体验	虽不影响正常用户，但增加运维成本

4. 解决方案设计与实现路径

为系统性解决此问题，需从异常监听、请求生命周期管理、框架配置三个层面协同处理。以下是推荐的技术路线：

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    errorHandler: '~/error-handler',
    experimental: {
      openAPI: false
    }
  },
  hooks: {
    'listen': (server) => {
      process.on('unhandledRejection', (reason: any) => {
        if (reason?.code === 'ECONNABORTED') {
          console.warn('[SSR] Client disconnected: ECONNABORTED');
          return;
        }
        console.error('Unhandled Rejection:', reason);
      });
    }
  }
});

5. 全局异常拦截策略

通过注册全局 unhandledRejection 监听器，对已知安全的网络中断类错误进行静默处理：

process.on('unhandledRejection', (err: Error) => {
  const isClientAbort = err?.message.includes('ECONNABORTED') ||
                        err?.message.includes('write EPIPE') ||
                        err?.message.includes('socket has been ended');

  if (isClientAbort) {
    // 记录为调试信息，不中断进程
    console.debug('[Network] Connection aborted by client');
    return;
  }

  // 非预期错误，交由监控系统捕获
  console.error('Critical Unhandled Rejection:', err);
  // 可集成 Sentry / Prometheus 上报
});

6. 请求生命周期增强控制

在数据获取层加入 abortSignal 支持，实现请求与客户端连接状态联动：

graph TD A[SSR Request Start] --> B{Client Connected?} B -- Yes --> C[Execute useFetch with AbortSignal] B -- No --> D[Skip Fetch, Return Empty] C --> E[Wait for API Response] E --> F{Client Still Alive?} F -- Yes --> G[Render Page] F -- No --> H[Cancel Fetch via AbortController]

示例代码：

// plugins/axios.ts 或自定义 fetch 封装
export function createSafeFetch(event: H3Event) {
  const controller = new AbortController();
  event.node.req.socket.on('close', () => {
    controller.abort();
  });

  return (url: string, options: any = {}) => {
    return globalThis.fetch(url, {
      ...options,
      signal: controller.signal
    }).catch(err => {
      if (err.name === 'AbortError') {
        console.debug('[Fetch] Cancelled due to client disconnect');
        return { data: null };
      }
      throw err;
    });
  };
}

7. Nitro 自定义错误处理器

利用 Nitro 提供的 errorHandler 能力，在服务端中间件层级拦截底层异常：

// error-handler.ts
export default function (error: Error, event: any) {
  if (error.message.includes('ECONNABORTED')) {
    // 不抛出错误，仅记录
    console.log(`[Nitro] Render interrupted: ${event.req.url}`);
    return;
  }
  // 继续传播其他错误
  console.error(error);
}

8. 运维与监控建议

结合 APM 工具（如 Datadog、New Relic）建立分类指标：

• metric.ssr.client_abort_count: 按路由统计连接中断次数
• trace.span.tag.is_client_initiated: 标记是否由客户端中断
• 设置告警规则：仅当非 ECONNABORTED 类异常持续上升时触发

同时优化反向代理配置，避免过早切断连接：

# Nginx 示例配置
location / {
  proxy_read_timeout 60s;
  proxy_send_timeout 60s;
  proxy_ignore_client_abort off; # 确保后端感知连接中断
}