JavaScript AbortSignal.timeout 和手动 AbortController 怎么选

前端请求里的“超时”和“取消”经常被写成同一段代码，但它们的触发者不同：AbortSignal.timeout(ms) 适合固定期限，AbortController 适合按钮、路由切换或业务状态主动结束。两者都能传给 fetch 的 signal，需要同时支持时，再用 AbortSignal.any() 合并。

简单选择：只有固定时限就用 AbortSignal.timeout；需要外部动作就用 AbortController；两种条件同时存在就组合两个 signal，并按异常名称区分提示。

固定超时和手动取消，解决的是两种不同的触发条件

如果接口只需要“最多等待 5 秒”，直接把超时 signal 交给 fetch，调用方不必保存 controller：

async function loadProfile() {
  // 这是固定期限：5 秒 active time 后由 signal 自动终止
  const signal = AbortSignal.timeout(5000);

  try {
    const response = await fetch('/api/profile', { signal });
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return await response.json();
  } catch (error) {
    // TimeoutError 表示期限到了，适合提示“请求超时”
    if (error.name === 'TimeoutError') throw new Error('请求超过 5 秒未完成');
    throw error;
  }
}

如果终止原因来自用户或页面生命周期，就让业务持有 controller。例如用户切换搜索词时，先取消上一轮请求：

let currentController;

async function search(keyword) {
  // 新一轮搜索开始前，结束上一轮请求
  currentController?.abort('搜索词已改变');
  currentController = new AbortController();

  const response = await fetch(`/api/search?q=${encodeURIComponent(keyword)}`, {
    // controller 只负责发信号，真正执行取消的是 fetch
    signal: currentController.signal
  });
  return response.json();
}

两者的差异可以压缩成一张表：

用 AbortSignal.any 把超时与用户操作合成一个信号

搜索、上传和生成报告常常既不能无限等待，又必须允许用户主动停止。此时分别创建两个 signal，再用 AbortSignal.any() 得到“任一条件发生就结束”的请求信号：

async function downloadReport() {
  const controller = new AbortController();
  const timeoutSignal = AbortSignal.timeout(15000);
  // 任意一个来源发出 abort，combinedSignal 都会终止 fetch
  const combinedSignal = AbortSignal.any([
    controller.signal,
    timeoutSignal
  ]);

  const cancelButton = document.querySelector('#cancel-report');
  const cancel = () => controller.abort();
  cancelButton.addEventListener('click', cancel, { once: true });

  try {
    const response = await fetch('/api/report', { signal: combinedSignal });
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return await response.blob();
  } catch (error) {
    // 组合 signal 会保留先发生的原因，用它决定界面文案
    if (error.name === 'TimeoutError') throw new Error('报表生成超时，请稍后重试');
    if (error.name === 'AbortError') return null; // 用户主动取消不提示故障
    throw error;
  } finally {
    // 防止组件销毁后还保留按钮监听
    cancelButton.removeEventListener('click', cancel);
  }
}

注意，AbortSignal.any() 只组合触发条件，不会把 signal 变成可复用对象。一个请求结束后，不要把已经 aborted 的 signal 放进下一次 fetch。

生产代码如何区分超时、用户取消和网络错误

不要只写一个“请求失败”提示。超时说明预算不足，用户取消通常无需报错，而网络错误还可能需要重试。捕获异常时至少按 name 分层，并把不可预期的错误继续抛给统一错误边界。

还有两个容易忽略的边界：第一，AbortSignal.timeout() 的计时基于 active time，页面进入 bfcache 或 worker 被挂起时可能暂停；第二，signal 一旦 aborted 就不能恢复。因此把 controller 放在“当前请求”作用域内，或在开始新任务时明确替换引用。

兼容旧浏览器时怎样保留同一套调用方式

AbortSignal.timeout() 属于较新的浏览器能力。需要兼容旧环境时，用 controller 和普通定时器实现同样的 signal 形状：

function timeoutSignal(ms) {
  const controller = new AbortController();
  // 旧环境用 controller 发出默认 AbortError
  const timerId = setTimeout(() => controller.abort(), ms);

  return { signal: controller.signal, cancel: () => clearTimeout(timerId) };
}

async function loadWithFallback() {
  const timeout = timeoutSignal(5000);
  try {
    const response = await fetch('/api/data', { signal: timeout.signal });
    return await response.json();
  } finally {
    // 成功、失败、取消都要清理定时器
    timeout.cancel();
  }
}

这个降级实现的错误名通常是 AbortError，不能像原生 timeout() 那样天然区分“超时”和“用户取消”。如果产品必须区分，可在 controller.abort(new DOMException('Timeout', 'TimeoutError')) 中传入明确 reason，并继续沿用同一套 catch 分支。

相关问题

AbortSignal.timeout 能在请求成功后手动清除吗？

它没有直接的取消方法。若需要确定地提前取消计时器，应使用 AbortController 加 setTimeout，并在 finally 中 clearTimeout。

AbortController 可以给多个请求共用吗？

可以让一个 signal 同时通知多个请求，但 signal 一旦 aborted，所有关联操作都会受到影响；独立任务最好各自创建 controller。

为什么 catch 里不建议只判断 AbortError？

固定超时通常以 TimeoutError 表示。只判断 AbortError 会把超时漏进通用网络错误分支，导致提示和重试策略不准确。