Node.js中设置HTTP请求超时的几种方式

在 Node.js 中发起 HTTP 请求时，默认情况下多数内置函数与网络客户端不会为你设置全局超时。若远端服务器宕机、链路丢包或由于代理故障处于未响应状态，挂起的请求连接可能长期霸占套接字资源，最终导致服务端连接池耗尽或进程崩溃。本文完整总结在 Node.js 环境下设置 HTTP 请求超时的四种主流手段：原生 http/https 模块、现代内置 fetch 配合 AbortSignal、主流三方库 Axios，以及现代高性能网络引擎 Undici/Got 的细粒度超时方案，并深入解析不同场景下的超时触发机制与核心避坑点。

图 0：Node.js HTTP 请求超时四大主流方案全景对照

一、原生 http/https 模块：req.setTimeout 与显式销毁

在不引入任何外部依赖的场景下，Node.js 提供了内置的 http 与 https 模块。在原生模块中，超时既可以在请求配置参数中通过 timeout 属性指定，也可以通过调用 req.setTimeout(ms) 方法设置。

但初学者最常犯的严重错误，是误以为设置了超时时间，底层请求就会自动取消。在 Node.js 原生设计中，req.setTimeout 仅仅是底层 Socket 触发了 'timeout' 事件，请求本身并不会被主动终止，TCP 套接字依然保持打开，直到服务端返回或操作系统强行关闭。

1. 完整代码示例：捕获超时并销毁请求

const http = require('http');

const options = {
  hostname: 'example.com',
  port: 80,
  path: '/api/data',
  method: 'GET',
  timeout: 5000 // 单位：毫秒（5秒）
};

const req = http.request(options, (res) => {
  let body = '';
  res.on('data', (chunk) => { body += chunk; });
  res.on('end', () => {
    console.log('响应完成:', body);
  });
});

// 监听超时事件：必须显式调用 req.destroy() 中断请求！
req.on('timeout', () => {
  console.error('请求已超时，正在强行销毁连接...');
  req.destroy(new Error('Request timeout after 5000ms'));
});

// 必须监听 error 事件，防止未捕获异常导致进程退出
req.on('error', (err) => {
  console.error('发生网络错误或超时销毁:', err.message);
});

req.end();

图 1：原生 http 模块超时捕获与 req.destroy() 关键执行时序

二、现代标准方式：内置 fetch 与 AbortSignal

从 Node.js 18 开始，全局内置了与浏览器标准高度一致的 fetch API。在现代异步编程中，终止网络请求的标准化机制是 AbortController 和 AbortSignal。

不同于原生 http 模块的空闲超时，fetch 结合信号机制提供的是全局绝对超时（End-to-End Timeout）。只要在规定时间内响应未就绪，Promise 会立刻被 Reject 并自动释放底层流资源。

1. 极简方式：使用 AbortSignal.timeout()（推荐）

如果你使用的是 Node.js 18.0.0 以上版本，设置超时最为优雅的方式是直接传入 AbortSignal.timeout(ms)：

async function requestWithTimeout() {
  try {
    const response = await fetch('https://httpbin.org/delay/6', {
      // 设置 4 秒绝对超时，超时后自动中止请求
      signal: AbortSignal.timeout(4000)
    });
    const data = await response.json();
    console.log('数据请求成功:', data);
  } catch (err) {
    if (err.name === 'TimeoutError') {
      console.error('HTTP请求因超出 4000ms 被中止:', err.message);
    } else {
      console.error('发生其他请求异常:', err);
    }
  }
}

requestWithTimeout();

2. 复合控制：结合 AbortController 与业务手动取消

如果你既需要“定时超时自动取消”，又希望在某些业务场景下（如用户主动关闭页面、依赖服务降级）能“手动提前取消”，可使用 AbortController 显式绑定：

async function fetchWithController() {
  const controller = new AbortController();
  // 设置 5 秒定时器
  const timer = setTimeout(() => {
    controller.abort(new Error('自定义超时: 超过5秒未响应'));
  }, 5000);

  try {
    const response = await fetch('https://httpbin.org/get', {
      signal: controller.signal
    });
    const result = await response.text();
    return result;
  } catch (err) {
    if (controller.signal.aborted) {
      console.error('请求已被终止，原因:', controller.signal.reason);
    } else {
      console.error('网络请求失败:', err);
    }
  } finally {
    // 务必清理定时器，避免事件循环空转
    clearTimeout(timer);
  }
}

图 2：Fetch 结合 AbortSignal 的声明式超时信号广播与异常处理机制

三、流行三方库：Axios 的 timeout 配置与行为边界

axios 是目前国内生产环境中最广泛使用的 HTTP 客户端之一。Axios 的配置极为直观，直接在请求配置或实例默认配置中加入 timeout 属性即可。

1. 基础用法与错误识别

const axios = require('axios');

// 创建带统一超时限制的实例
const apiClient = axios.create({
  baseURL: 'https://api.example.com',
  timeout: 5000 // 请求超过 5000ms 将自动中断
});

async function fetchUserData(userId) {
  try {
    const response = await apiClient.get(`/users/${userId}`);
    return response.data;
  } catch (error) {
    // 关键：Axios 超时错误的特征判断
    if (error.code === 'ECONNABORTED' && error.message.includes('timeout')) {
      console.error('业务请求超时，已触发熔断或降级处理');
    } else {
      console.error('其他网络或业务错误:', error.message);
    }
  }
}

2. Axios 超时的定义与边界

读者需要明确，Axios 在 Node.js 端底层依托 http/https 模块，默认的 timeout 计时覆盖的是发起请求到服务端返回响应头（Headers）并建立响应流之间的耗时。

• 连接阶段：如果与远程服务器建立 TCP 连接超时，或连接被防火墙静默丢弃，将在达到 timeout 时触发 ECONNABORTED。
• 长响应体传输：如果响应头已经成功接收，但随后的 Response Body 数据传输极为缓慢（如大文件下载中途卡顿），默认配置可能不会继续触发该超时。针对这种场景，需要结合 signal: AbortSignal.timeout(ms) 进行端到端强制限时。

四、进阶高并发方案：Undici 与 Got 的细粒度阶段超时

在微服务架构或大规模爬虫、高并发网关中，粗粒度的“总超时”往往不能满足排障要求。一次 HTTP 通信包含以下关键物理阶段：

1. DNS 解析（Lookup）：域名转换为 IP 地址的时间。
2. 连接握手（Connect）：TCP 三次握手与 TLS 加密握手的时间。
3. 首包等待（Headers）：请求发完后等待服务端返回首个字节或 Headers 的时间。
4. 数据读取（Body/Read）：从服务端读取全部响应正文的时间。

图 3：各 HTTP 请求客户端超时覆盖阶段全貌对比

1. Undici：Node.js 底层引擎的分阶段超时

undici 是 Node.js 官方支持的新一代高性能 HTTP/1.1 客户端（也是 Node.js 内置 fetch 的底层引擎）。它直接支持 headersTimeout 与 bodyTimeout：

const { request } = require('undici');

async function callUndici() {
  try {
    const { statusCode, body } = await request('https://api.example.com/items', {
      method: 'GET',
      headersTimeout: 3000, // 等待响应头的最长耗时 3 秒
      bodyTimeout: 5000     // 响应体流式传输的最长时间 5 秒
    });
    const result = await body.json();
    console.log('状态码:', statusCode, '数据:', result);
  } catch (err) {
    console.error('Undici阶段超时或网络错误:', err.message);
  }
}

2. Got 库的对象式阶段超时配置

如果你使用 got 库，它提供了最为详细的阶段超时对象（timeout object）：

const got = require('got');

async function fetchWithGot() {
  try {
    const response = await got('https://api.example.com/large-data', {
      timeout: {
        lookup: 1000,    // DNS 查询耗时不得超过 1 秒
        connect: 2000,   // TCP 握手建连不得超过 2 秒
        response: 4000,  // 首个响应头到达不得超过 4 秒
        read: 5000       // 数据包间隔不得超过 5 秒
      }
    });
    console.log(response.body);
  } catch (error) {
    if (error.name === 'TimeoutError') {
      console.error(`阶段 [${error.event}] 发生超时:`, error.message);
    }
  }
}

五、综合选型建议与生产环境避坑指南

在实际生产选型中，没有所谓“最好的方式”，只有最契合业务架构约束的方案。

图 4：Node.js 项目 HTTP 请求超时方案选型决策图

生产环境三大避坑军规

1. 区分连接超时（Connect Timeout）与读取超时（Read Timeout）： 在内网微服务之间通信，TCP 握手通常只需数毫秒，因此 connect 超时可以设置得很短（例如 1~2 秒）；而业务接口数据运算耗时较长，response 或 read 超时可放宽至 5~10 秒。将两者混为一谈会导致网络抖动时长时间浪费线程，或由于业务轻微耗时被误杀。
2. 重视 HTTP Keep-Alive 与连接池的相互影响： 使用 http.Agent 或 Undici 连接池复用长连接时，如果远端服务器因为空闲超期（Keep-Alive Timeout）主动关闭了连接，客户端刚好发起请求，可能遇到 ECONNRESET 错误。生产环境应将客户端的空闲等待时间设置为短于上游网关（如 Nginx）的 keepalive_timeout。
3. 超时后的重试必须满足幂等性： 当收到超时错误时，这并不代表远程服务器没有执行该请求，很有可能服务器已经成功落库扣款，只是网络响应在传输途中丢包。因此只有 GET、PUT 等具备幂等特征的请求才可在超时后直接重试；对于 POST 支付或提交订单请求，必须依托业务流水号或唯一幂等 Token，不可盲目自动重试。