AbortSignal.timeout 怎样给请求设置超时

给浏览器里的 fetch() 设置一个固定超时，最短写法是把 AbortSignal.timeout(5000) 传给请求的 signal：超过 5000 毫秒后，未完成的请求会被终止，并以名字为 TimeoutError 的异常拒绝。它只负责“到时间自动取消”，HTTP 状态码仍然要通过 response.ok 或 response.status 单独判断。

官方文档：https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/timeout_static

最小写法：把超时信号交给 fetch

AbortSignal.timeout() 返回一个尚未取消的 AbortSignal。下面的 5000 是毫秒，表示请求操作最多等待五秒。超时原因不是普通的网络错误，而是一个 TimeoutError。

async function loadProfile(userId) {
  const url = `/api/users/${encodeURIComponent(userId)}`;

  try {
    // 让请求最多等待 5 秒，超时后由 AbortSignal 终止 fetch。
    const response = await fetch(url, {
      signal: AbortSignal.timeout(5_000),
      headers: { "Accept": "application/json" },
    });

    // fetch 遇到 404、500 仍会得到 Response，需要显式检查状态。
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }

    // 在 signal 仍有效时读取响应体，避免只拿到响应头就结束。
    return await response.json();
  } catch (error) {
    if (error?.name === "TimeoutError") {
      throw new Error("请求超过 5 秒仍未完成", { cause: error });
    }
    throw error;
  }
}

这里的信号是一次性的：一个信号一旦进入 aborted 状态，就不适合再拿去驱动下一次请求。实际项目应当在每次请求调用时重新创建 AbortSignal.timeout()，不要把它缓存成全局变量反复使用。

超时、HTTP 错误和网络错误不是一回事

请求超时只代表信号触发了取消，不代表服务端返回了某个 HTTP 状态。Fetch API 在收到 404 或 500 时通常仍会兑现 Promise，因此需要把两层判断分开：

• TimeoutError：等待超过了时限。
• AbortError：请求被用户操作、页面逻辑或其他主动取消动作终止。
• response.ok === false：服务端返回了非 2xx 状态。
• TypeError 或其他异常：常见于网络失败、请求构造失败或运行环境不支持该方法。

不要只写一个“请求失败”的提示，否则用户无法知道是应当重试、延长时限，还是修正请求参数。

同时支持用户取消和自动超时

如果页面既有“取消”按钮，又需要兜底超时，可以用 AbortSignal.any() 合并两个信号。数组中任意一个信号先取消，合并信号就会取消；超时信号本身不会因为用户提前取消而被手动清除。

async function requestJson(url, cancelSignal) {
  const timeoutSignal = AbortSignal.timeout(8_000);
  // 任意一个信号触发，fetch 都会结束；保留原始原因便于分类处理。
  const signal = AbortSignal.any([cancelSignal, timeoutSignal]);

  try {
    const response = await fetch(url, { signal });

    // HTTP 错误不是 fetch 的 reject，需要把状态转成业务异常。
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }

    // 等待正文读完，调用方拿到的是完整 JSON 而不是只有响应头。
    return await response.json();
  } catch (error) {
    // timeout 与用户 abort 使用不同名字，提示和重试策略可以分别处理。
    if (error?.name === "TimeoutError") {
      return { kind: "timeout", message: "服务响应超时" };
    }
    if (error?.name === "AbortError") {
      return { kind: "cancelled", message: "请求已取消" };
    }
    throw error;
  }
}

const controller = new AbortController();
cancelButton.addEventListener("click", () => {
  // 用户主动取消只影响本次请求，不复用已取消的 controller。
  controller.abort();
});

参数和生命周期要注意什么

AbortSignal.timeout(time) 的参数是毫秒，必须落在非负整数和 Number.MAX_SAFE_INTEGER 的范围内。它使用的是活动时间语义：文档进入浏览器的往返缓存，或相关 Worker 被挂起时，计时可能暂停，不应把它简单理解成永远按墙上时钟流逝的倒计时。

另外，AbortSignal.timeout() 本身没有“提前取消计时器”的接口。若操作很快完成，通常不需要为一次短生命周期请求额外处理；但如果长期持有信号并自行注册 abort 监听器，应在操作结束后移除自己添加的监听器。需要明确控制计时器清理时，才考虑用 AbortController 加 setTimeout()，并在 finally 中调用 clearTimeout()。

兼容性与选型速查

MDN 将该静态方法标为广泛可用，浏览器支持起点为 2024 年 4 月；但真正面向旧版内嵌 WebView 或特殊运行环境发布时，仍应按目标浏览器矩阵确认。不要把“请求很慢”直接等价为“HTTP 失败”，也不要在一次 signal 已取消后继续复用它。

结论

固定超时的核心只有两步：每次请求新建 AbortSignal.timeout(ms)，再把它放进 fetch 的 signal 选项；捕获异常时优先区分 TimeoutError 与 AbortError，收到响应后再检查 response.ok。如果调用方还需要手动取消，再用 AbortSignal.any() 合并信号。

常见问题

AbortSignal.timeout 的单位是什么？

单位是毫秒，例如 3000 表示三秒。使用数字分隔符 3_000 可以让代码更容易阅读。

fetch 超时后一定会抛出 TimeoutError 吗？

由 AbortSignal.timeout() 触发的取消，其原因是 TimeoutError；网络层或其他代码也可能以不同异常结束，因此不要只根据“等待时间长”猜测错误类型。

返回 500 时为什么没有进入 catch？

HTTP 500 通常仍然会得到一个 Response。只有在 !response.ok 时主动抛出异常，或者把状态转换成业务结果，才能让调用方统一处理。