JavaScript 教程:使用 AbortController 取消 fetch 请求与异步任务

原创2026-10-07 11:44:151,326 阅读
文章标签:文档/教程前端

JavaScript 教程:使用 AbortController 取消 fetch 请求与异步任务

fetch 返回的是 Promise,而 JavaScript 的 Promise 本身没有"取消"概念,因此当一个正在进行的网络请求不再需要时(例如用户已离开页面、切换了筛选条件、或超时),如何主动终止它就成了实际问题。本指南围绕 Modern JavaScript Tutorial(本仓库 1-js / 5-network 系列)中 Fetch: Abort 一章展开,系统讲解内建对象 AbortController 的用法:如何用它取消单个 fetch、一次取消多个并行请求,以及如何让自定义异步任务共享同一套取消机制。读完本文你将掌握一套不依赖任何第三方库、浏览器原生支持的请求取消方案,并能在实际项目中正确处理 AbortError。

AbortController 对象:为"可取消操作"而生的内建对象

JavaScript 语言层面没有"中止一个 Promise"的标准 API,但存在一个专为此类场景设计的内建对象:AbortController。它不仅适用于 fetch,也可以服务于其他任意异步任务。

创建控制器非常简单:

let controller = new AbortController();

控制器是一个极其简单的对象,只有两部分:

  • 一个方法 abort();
  • 一个属性 signal,允许在其上挂载事件监听器。

当调用 abort() 时,会发生两件事:

  • controller.signal 触发 "abort" 事件;
  • controller.signal.aborted 属性变为 true。

整个过程通常涉及两方参与者:

  1. 执行方可取消操作的一方:在 controller.signal 上设置事件监听器;
  2. 发起取消的一方:在需要时调用 controller.abort()。

下面是不涉及 fetch 的完整示例(来自 article.md),演示了这一事件传播机制:

let controller = new AbortController();
let signal = controller.signal;

// 执行可取消操作的一方拿到 signal 对象
// 并注册监听器,在 controller.abort() 被调用时触发
signal.addEventListener('abort', () => alert("abort!"));

// 另一方(可在任意时刻)发起取消:
controller.abort(); // abort!

// 事件已触发,signal.aborted 变为 true
alert(signal.aborted); // true

由此可见,AbortController 本质上只是"调用 abort() → 在 signal 上派发 abort 事件"这一交互的标准化载体。类似的"事件监听"逻辑你完全可以自己实现,但真正有价值的是:fetch 原生就认识 AbortController,二者深度集成,这正是它不可替代的地方。

与 fetch 集成:把 signal 作为请求选项传入

要让一个 fetch 可以被取消,只需要把 AbortController 的 signal 属性作为 fetch 的第二个参数(选项对象)传入:

let controller = new AbortController();
fetch(url, {
  signal: controller.signal
});

fetch 会在内部监听 signal 上的 abort 事件。此后随时调用:

controller.abort();

请求即被终止。在 Fetch API 一章 的选项清单中,signal 选项的官方说明正是 // AbortController to abort request,与本文所述一致,可见它是 fetch 选项体系中的一等公民。

被中止时:Promise 以 AbortError 拒绝

当 fetch 被中止时,其返回的 Promise 会以名为 AbortError 的错误拒绝,因此必须在 try..catch(或 .catch)中处理它,避免产生未捕获的 Promise 异常。

以下是文档中的完整示例——发起请求 1 秒后自动中止,并区分 AbortError 与其他错误(见 article.md):

// 1 秒后中止
let controller = new AbortController();
setTimeout(() => controller.abort(), 1000);

try {
  let response = await fetch('/article/fetch-abort/demo/hang', {
    signal: controller.signal
  });
} catch(err) {
  if (err.name == 'AbortError') { // 处理 abort() 触发的中止
    alert("Aborted!");
  } else {
    throw err; // 其他错误照常抛出
  }
}

这里请求的地址 /article/fetch-abort/demo/hang 在本仓库中有对应的演示服务器实现:demo.view/server.js。它基于 Koa 构建,其关键端点是一个"永不返回"的挂起请求:

router.get('/hang', async (ctx) => {
  await new Promise(() => {}); // 永不 resolve,模拟长时间挂起的请求
});

await new Promise(() => {}) 使该请求永远不会完成,是验证 AbortController 取消能力最直接的测试场景:若不中止,这个 fetch 会一直挂起;调用 controller.abort() 后,Promise 立即以 AbortError 拒绝,进入 catch 分支。

工程实践要点:

  • 判断中止请使用 err.name == 'AbortError',不要依赖错误消息文本;
  • 捕获到 AbortError 后通常无需提示用户"网络错误",因为这是应用主动取消,属于预期流程;
  • 其他非中止错误(如网络断开、HTTP 层失败)应原样抛出或单独处理,切勿与取消混为一谈。

AbortController 可扩展:一次取消所有并行请求

AbortController 是可扩展(scalable)的——同一个控制器可以同时取消多个 fetch。假设我们并行抓取一批 URL,并希望用一个控制器统一管理它们的生命周期:

let urls = [...]; // 需要并行 fetch 的 URL 列表

let controller = new AbortController();

// fetch 的 Promise 数组
let fetchJobs = urls.map(url => fetch(url, {
  signal: controller.signal
}));

let results = await Promise.all(fetchJobs);

// 只要在任意位置调用 controller.abort(),
// 所有 fetch 会同时被中止

每个 fetch 都监听同一个 signal,因此一次 abort() 调用即可让整个批处理任务全部终止。这在"用户取消了整页加载""分页/搜索请求竞态""批量预取被废弃"等场景中尤其有用。

自定义异步任务与 fetch 共享取消信号

如果你有自己的异步任务(不是 fetch),同样可以把它们纳入这套取消机制:只需要在自己的任务里监听 signal 的 abort 事件即可。

下面是文档中的组合示例——自定义任务 ourJob 与多个 fetch 并行等待,共享同一个控制器(见 article.md):

let urls = [...];
let controller = new AbortController();

let ourJob = new Promise((resolve, reject) => { // 我们的自定义任务
  ...
  controller.signal.addEventListener('abort', reject); // 被中止时拒绝
});

let fetchJobs = urls.map(url => fetch(url, { // fetch 任务
  signal: controller.signal
}));

// 并行等待所有 fetch 和我们的任务
let results = await Promise.all([...fetchJobs, ourJob]);

// 只要调用 controller.abort(),
// 所有 fetch 与 ourJob 会一并被中止

这里 controller.signal.addEventListener('abort', reject) 让自定义任务在中止信号到来时以 reject 结束——reject 被调用时传入的默认参数会使得 ourJob 以一个错误被拒绝,从而与 fetchJobs 的中止行为保持一致。这种"统一信号、统一取消"的模式意味着:无论任务来源是 fetch 还是手写逻辑,一套 AbortController 即可统管全部。

需要留意的是,若要在中止后区分"被取消"与"正常失败",自定义任务中更稳妥的写法是显式构造 AbortError(如 reject(new DOMException('Aborted', 'AbortError'))),并让 Promise 链按相同约定处理——这与 fetch 的内建行为对齐。

相关章节联动

AbortController 在教程中并非孤立存在,它与以下内容相互呼应:

  • Promise API(Promise.all):该章明确指出 Promise.all 本身不会取消任何 Promise,因为 Promise 没有取消概念,并预告"取消"由 AbortController 补足;
  • Fetch API 选项清单:signal: undefined, // AbortController to abort request 是该选项的权威出处;
  • XMLHttpRequest:XHR 体系也有对应的 abort 事件语义,可对照理解不同请求 API 的取消模型。

总结

  • AbortController 是一个极简对象:调用 abort() 方法时,会在其 signal 属性上触发 abort 事件,并将 signal.aborted 置为 true;
  • fetch 与之深度集成:把 signal 作为选项传入后,fetch 会监听它,从而可以被中止;中止时 Promise 以 AbortError 拒绝,需用 try..catch 配合 err.name == 'AbortError' 处理;
  • 该模式可扩展:一个控制器能同时取消多个并行 fetch;自定义异步任务同样可以监听 signal 的 abort 事件,与 fetch 共享同一套取消机制;
  • "调用 abort() → 监听 abort 事件"的交互简单且通用,即使不使用 fetch,也可以把 AbortController 作为通用的任务取消基础设施。
登录后查看全文
en.javascript.info