AbortSignal.any 触发后怎样判断来自超时还是手动取消

AbortSignal.any() 触发后，直接看组合信号的 reason。标准超时信号会给出名为 TimeoutError 的 DOMException；无参数调用 controller.abort() 时，手动取消默认是 AbortError。

最短答案：在 catch 中读取 combined.reason，不要只猜错误文案。若业务必须百分之百知道“哪个输入信号获胜”，就为手动取消设置独有的 reason，或者在组合前记录来源。

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

最小可用写法：判断 TimeoutError 和 AbortError

浏览器原生组合已经把原因传递做好了。下面的代码无需额外布尔变量，也不需要把超时包装成 Promise.race()：

async function loadData(url, cancelController) {
  const timeoutSignal = AbortSignal.timeout(8_000);
  const combined = AbortSignal.any([
    cancelController.signal,
    timeoutSignal,
  ]);

  try {
    const response = await fetch(url, { signal: combined });
    return await response.json();
  } catch (error) {
    // 组合信号保存的是第一个中止源的原因。
    const reason = combined.reason;

    if (reason instanceof DOMException && reason.name === "TimeoutError") {
      throw new Error("请求超时，请稍后重试", { cause: reason });
    }
    if (reason instanceof DOMException && reason.name === "AbortError") {
      throw new Error("请求已由用户取消", { cause: reason });
    }

    // 非中止错误仍按网络或业务错误向上抛出。
    throw error;
  }
}

这段判断成立的前提是：超时来自 AbortSignal.timeout()，手动取消使用默认的 controller.abort()。此时两个标准异常的 name 不同，足以完成界面提示和日志分类。

旧写法的问题：两个布尔值会和异常发生竞态

早期代码常在超时回调里设置 didTimeout = true，在按钮事件里设置 didCancel = true，再用 Promise.race() 判断。问题是状态分散：请求可能已经结束，定时器仍会触发；两个事件几乎同时发生时，最终布尔值不一定代表真正让 fetch 失败的那个原因。

AbortSignal.any() 把这套约定收敛为“第一个中止获胜”。组合信号一旦中止，aborted 变为 true，reason 被固定，后续其他输入再中止也不会改写它。

any 的新语义：只保留第一个 reason

规范语义可以概括为“原因传播”，不是“来源索引”。如果输入信号在组合之后异步中止，最先触发者的 reason 成为结果；如果创建组合信号时已有输入处于中止状态，则按可迭代对象顺序采用第一个已中止输入的 reason。

const first = new AbortController();
const second = new AbortController();

first.abort("manual-A");
second.abort("manual-B");

// 两个输入都已中止，数组中更靠前的 reason 被采用。
const combined = AbortSignal.any([first.signal, second.signal]);
console.log(combined.aborted); // true
console.log(combined.reason);  // "manual-A"

这也带来一个容易漏掉的边界：组合信号可能在构造完成时就已经中止，此后才注册的 abort 监听器不会补发事件。调用异步任务前可先检查 combined.aborted，或直接调用 combined.throwIfAborted()。

更稳的方案：给手动取消写入可识别 reason

只判断 AbortError 适合简单页面。若一个请求可能因关闭弹窗、切换路由、退出账号等多种人工动作取消，应该把来源写进 reason，而不是依赖 message 文案。

class RequestCancelError extends Error {
  constructor(source) {
    super(`请求被取消：${source}`);
    this.name = "RequestCancelError";
    this.source = source;
  }
}

const manualController = new AbortController();
const timeoutSignal = AbortSignal.timeout(8_000);
const combined = AbortSignal.any([
  manualController.signal,
  timeoutSignal,
]);

function cancelFromDialog() {
  // abort(reason) 接受任意 JavaScript 值，这里使用可识别的 Error。
  manualController.abort(new RequestCancelError("dialog-close"));
}

try {
  await fetch("/api/report", { signal: combined });
} catch (error) {
  const reason = combined.reason;

  if (reason instanceof RequestCancelError) {
    console.info("manual-cancel", { source: reason.source });
  } else if (reason?.name === "TimeoutError") {
    console.warn("request-timeout");
  } else {
    throw error;
  }
}

自定义 reason 的价值不是换一个错误字符串，而是建立稳定契约：界面根据 source 决定是否提示，监控系统根据类型归类，调用方也能避免把用户取消计入网络失败率。

什么时候 reason 仍然不够

AbortSignal.any() 没有 sourceIndex、winner 之类的属性。如果两个控制器都用默认 AbortError，或者第三方库给多个信号传入同一个 Error 对象，组合后只能知道“为什么中止”，无法知道“哪一个输入触发”。

来源身份是硬需求时，可以在组合前给每个信号安装一次性监听器，并在第一个事件到达时记录标签：

function combineWithSource(entries) {
  let source = null;
  const cleanups = [];

  for (const [name, signal] of entries) {
    const remember = () => {
      // JavaScript 单线程事件处理下，只记录第一个观察到的来源。
      if (source === null) source = name;
    };
    signal.addEventListener("abort", remember, { once: true });
    cleanups.push(() => signal.removeEventListener("abort", remember));
  }

  const signal = AbortSignal.any(entries.map(([, item]) => item));

  // 已中止输入不会为后注册监听器补发事件，按数组顺序补记。
  if (signal.aborted && source === null) {
    source = entries.find(([, item]) => item.aborted)?.[0] ?? null;
  }

  return {
    signal,
    getSource: () => source,
    dispose: () => cleanups.forEach((cleanup) => cleanup()),
  };
}

操作完成后调用 dispose()，移除业务自己添加的监听器。注意，这个记录器的语义仍是“第一个被当前代码观察到的中止源”，不要把它扩展成不存在的全局时钟排序。

不要只检查 catch 到的 error

现代 Fetch 会用信号的中止原因拒绝 Promise，因此许多场景下 error 和 combined.reason 是同一个值。不过把组合信号保留在作用域中并读取其 reason 更清楚：只有 combined.aborted 为 true 时，才应把失败归类为这组取消源；普通网络错误不应被误判成超时。

try {
  return await fetch(url, { signal: combined });
} catch (error) {
  if (!combined.aborted) {
    throw error; // DNS、断网、CORS 等并不是主动取消。
  }

  const reason = combined.reason;
  if (reason?.name === "TimeoutError") {
    return { ok: false, kind: "timeout" };
  }
  return { ok: false, kind: "cancel", reason };
}

兼容旧环境：先做能力检测

当前主流浏览器已支持 AbortSignal.any()，但嵌入式 WebView、旧版企业浏览器或较旧的 JavaScript 运行时可能缺失。不要仅凭 User-Agent 判断，直接检测方法是否存在。

function anySignal(signals) {
  if (typeof AbortSignal.any === "function") {
    return AbortSignal.any(signals);
  }

  const controller = new AbortController();
  const abortFrom = (signal) => {
    // 关键是把源信号的 reason 继续传下去。
    if (!controller.signal.aborted) controller.abort(signal.reason);
  };

  for (const signal of signals) {
    if (signal.aborted) {
      abortFrom(signal);
      break;
    }
    signal.addEventListener("abort", () => abortFrom(signal), { once: true });
  }
  return controller.signal;
}

这个轻量降级保留了首因传播，但没有完整复制原生实现的弱引用和监听器生命周期优化。长生命周期应用应使用经过维护的 polyfill，并在任务结束后清理自己添加的监听器。

选择哪种判断方式

常见问题

后中止的信号会覆盖 combined.reason 吗？

不会。组合信号只中止一次，第一个原因确定后保持不变。

能用 error.message 判断超时吗？

不建议。message 可能随浏览器、语言环境或自定义 reason 改变；优先检查类型、name 或业务字段。

手动取消也能传 TimeoutError 吗？

可以，abort(reason) 接受任意值。正因如此，TimeoutError 代表当前约定的原因，不是无法伪造的来源身份。业务代码应控制 reason 契约。

组合信号中止后会取消 timeout 的计时器吗？

不会。中止组合信号不等于反向中止其他输入，AbortSignal.timeout() 的内部计时仍按其规则完成。若必须提前清除长定时器，应使用 AbortController、setTimeout() 和 clearTimeout() 自行管理。

所以，判断超时还是手动取消的核心不是再维护一套状态，而是把 reason 当成取消协议：标准场景看 TimeoutError 与 AbortError；复杂场景为每种来源设置稳定 reason；只有在原因值可能相同且必须追踪输入身份时，才额外记录源信号。