前端 AbortSignal.timeout 如何避免请求悬挂：超时信号与 fetch 清理边界

页面里的请求最怕“看起来发出去了，界面却一直等”。把超时写成一个明确的 AbortSignal，可以让 fetch 在等待响应或读取响应体时及时结束，同时保留“超时”“用户取消”“网络失败”这三类不同原因。本文用一个查询函数把这条边界落到可运行代码里。

优先用 AbortSignal.timeout(毫秒数) 表达自动超时；需要同时支持手动取消时，用 AbortSignal.any() 合并信号，并在 catch 中按 TimeoutError、AbortError 和其他错误分别处理。

请求为什么会一直挂着

fetch 返回的 Promise 只代表请求流程已经有了结果，并不保证服务端会在页面希望的时间内返回。更容易被忽略的是：即使响应头已经到达，后面的 response.json() 仍然可能等待响应体。如果只在按钮上做 loading 状态，而没有取消信号，用户切换页面后这条请求仍可能继续占用连接和业务处理时间。

这里的目标不是把所有慢请求都判成失败，而是给当前交互设一个可解释的边界：超过 5000 毫秒就结束本次等待，用户主动离开则按取消处理。

AbortSignal.timeout 如何接入 fetch

最小实现不需要额外的定时器。AbortSignal.timeout(5000) 返回一个会自动触发的信号，直接放进 fetch 的 signal 选项即可。

async function loadUserPanel(url) {
  const signal = AbortSignal.timeout(5000);

  try {
    const response = await fetch(url, { signal });
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }
    return await response.json();
  } catch (error) {
    if (error.name === "TimeoutError") {
      throw new Error("请求超过 5 秒仍未完成");
    }
    if (error.name === "AbortError") {
      throw new Error("请求已被主动取消");
    }
    throw error;
  }
}

图中只保留了这段代码真正存在的节点：AbortSignal.timeout 创建边界，fetch 接收信号，最后进入 TimeoutError 分支。响应体读取也在同一个 try 范围内，因此它没有被错误地当成另一个独立请求。

把用户取消和自动超时分开

搜索框、详情页和批量导出通常既要支持自动超时，也要支持用户点击“取消”。这时可以让 AbortController 负责手动取消，再用 AbortSignal.any() 合并两个信号，谁先触发就结束请求。

async function loadWithCancel(url, cancelButton) {
  const controller = new AbortController();
  const timeout = AbortSignal.timeout(5000);
  const signal = AbortSignal.any([controller.signal, timeout]);

  cancelButton.addEventListener("click", () => {
    controller.abort();
  }, { once: true });

  try {
    const response = await fetch(url, { signal });
    return await response.json();
  } catch (error) {
    if (signal.reason?.name === "TimeoutError") {
      return { ok: false, reason: "timeout" };
    }
    if (signal.reason?.name === "AbortError") {
      return { ok: false, reason: "cancelled" };
    }
    throw error;
  }
}

判断 signal.reason 比只看一个通用错误文本更可靠：超时返回可重试提示，用户取消则安静收起 loading。一次请求结束后不要复用已经触发过的 controller；新的请求必须创建新的 AbortController 和组合信号。

响应体读取阶段也要纳入边界

不要在 fetch() resolve 后立刻认为请求已经安全结束。MDN 的示例明确说明，如果在响应到达后、读取响应体前触发 abort，response.text() 等读取操作仍会以 AbortError 失败。因此 response.json() 应该和 fetch 放在同一个异常处理范围内，并在 UI 层统一关闭 loading。

如果接口返回非 2xx 状态，建议先检查 response.ok，再读取业务 JSON。HTTP 错误不是超时，也不应被伪装成“网络失败”。这种区分能让重试按钮只出现在真正适合重试的分支。

兼容降级与常见误区

旧浏览器如何降级

AbortSignal.timeout() 是 Baseline 2024 能力，面向旧环境时可以先检测它，再用 AbortController 和 setTimeout 组合出同样的边界。降级代码应清理定时器，避免请求已完成后还留下回调。

function timeoutSignal(ms) {
  if (typeof AbortSignal.timeout === "function") {
    return AbortSignal.timeout(ms);
  }

  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), ms);
  controller.signal.addEventListener("abort", () => {
    clearTimeout(timer);
  }, { once: true });
  return controller.signal;
}

三个容易踩中的边界

• 不要把同一个已 aborted 的 signal 传给下一次 fetch；它会立即失败。
• 不要只捕获 TimeoutError 而漏掉用户取消和普通网络异常。
• 不要在 finally 之前遗留 loading 状态；取消和响应体读取失败都要走清理。

常见问题

AbortSignal.timeout 的时间是从什么时候开始算？

它创建后就代表一个自动触发的时间边界，传入 fetch 后会影响请求及其响应体消费；具体暂停行为还会受到页面或 Worker 被挂起等运行环境影响。

TimeoutError 和 AbortError 有什么区别？

TimeoutError 表示 timeout 信号到期，AbortError 通常表示通过 AbortController 或浏览器操作主动取消。业务提示和是否允许重试可以据此分开。

AbortSignal.timeout 不支持时能不能继续用 fetch？

可以，用 AbortController 加定时器做降级，并在调用前检测静态方法是否存在。降级方案仍应覆盖 fetch 和响应体读取，并在请求结束时清理定时器。

小结

前端超时治理的关键不是给 fetch 外面套一个计时器，而是把同一个 AbortSignal 传入请求和响应体消费流程。自动超时使用 AbortSignal.timeout，手动取消使用 AbortController，组合场景用 AbortSignal.any；最后按 signal.reason 区分超时、取消和普通错误，页面状态才不会被一个模糊的“请求失败”牵着走。