JavaScript Promise.withResolvers 适合哪些事件桥接场景

Promise.withResolvers() 最适合“Promise 在这里交给调用方，但完成它的事件发生在另一个回调里”的桥接场景。典型例子包括等待一次 DOM 事件、给事件等待增加取消与超时、把 WebSocket 或流式事件改造成异步迭代器。它不让 Promise 变成多次完成，也不自动提供队列、清理、背压或取消机制。

官方文档：https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/withResolvers

先明确它解决的是作用域问题

Promise.withResolvers() 不接收参数，返回一个普通对象，其中包含新的 promise、用于成功完成的 resolve 和用于失败完成的 reject。它与“先声明两个变量，再在 new Promise() 执行器里赋值”的模式等价，只是表达更直接。

// 旧写法：为了把解析器带到执行器外部，需要先声明可变变量。
let resolveTask;
let rejectTask;
const task = new Promise((resolve, reject) => {
  resolveTask = resolve;
  rejectTask = reject;
});

// 新写法：Promise 与两个解析器在同一作用域内拿到。
const {
  promise: nextTask,
  resolve: resolveNextTask,
  reject: rejectNextTask,
} = Promise.withResolvers();

如果全部异步逻辑本来就能自然放在 Promise 执行器中，普通构造器仍然清楚。真正适合改用 withResolvers 的信号，是事件监听器需要只注册一次、完成入口分散在成功/失败/关闭回调中，或者每轮事件等待都要替换一组新的 Promise 与解析器。

MDN 将该特性列为 Baseline Widely available，并注明自 2024 年 3 月起在多种浏览器版本中可用。面向旧 WebView、旧 Electron 或未更新的企业终端时，仍应按项目的目标环境做特性检测，而不是仅凭现代桌面浏览器判断。

一次性事件等待要把清理写进桥接器

等待“组件准备完成”“弹窗关闭”或“某个自定义事件第一次出现”时，Promise.withResolvers() 能把事件回调与调用方的 await 连接起来。生产写法不能只调用 resolve，还要在任何结算路径中移除监听器和定时器。

function waitForEvent(target, type, { signal, timeout = 10_000 } = {}) {
  // 三个对象在桥接器内部创建，调用方最终只拿到 promise。
  const { promise, resolve, reject } = Promise.withResolvers();
  let settled = false;
  let timer;

  // 所有成功、失败、取消路径都调用同一清理函数。
  const cleanup = () => {
    target.removeEventListener(type, onEvent);
    signal?.removeEventListener("abort", onAbort);
    if (timer !== undefined) clearTimeout(timer);
  };

  // 防止事件、取消和超时竞争时重复执行副作用。
  const settleOnce = (settle, value) => {
    if (settled) return;
    settled = true;
    cleanup();
    settle(value);
  };

  const onEvent = (event) => settleOnce(resolve, event);
  const onAbort = () => {
    const reason = signal.reason ?? new DOMException("操作已取消", "AbortError");
    settleOnce(reject, reason); // 保留调用方提供的取消原因。
  };

  // 已取消的信号直接失败，避免注册永远不会清理的监听器。
  if (signal?.aborted) {
    onAbort();
    return promise;
  }

  target.addEventListener(type, onEvent, { once: true });
  signal?.addEventListener("abort", onAbort, { once: true });
  timer = setTimeout(() => {
    settleOnce(reject, new Error(`等待事件 ${type} 超时`));
  }, timeout);

  return promise;
}

调用方可以把取消权保留在自己的生命周期里：

// 页面卸载或组件销毁时，由调用方统一触发取消。
const controller = new AbortController();

try {
  const event = await waitForEvent(widget, "ready", {
    signal: controller.signal,
    timeout: 5_000, // 最多等待 5 秒，避免悬空任务。
  });
  console.info("组件已准备", event.type); // 只记录必要的生命周期信息。
} catch (error) {
  console.error("组件准备失败", error); // 失败交给上层决定降级或重试。
}

这里的安全边界很明确：调用方拥有 AbortController，但没有拿到桥接器的 resolve 和 reject。否则任何下游模块都能伪造“已准备”或“失败”状态，事件协议就失去了可信来源。

持续事件要把 Promise 当等待器，而不是消息容器

Promise 只能结算一次。WebSocket 的 message 会发生很多次，不能用同一个 resolve 接收全部消息。适合的结构是：事件监听器只注册一次；消息进入显式队列；当队列从空变为非空时，当前等待器负责唤醒消费者；消费者醒来后立刻创建下一组解析器。

async function* websocketMessages(socket, { signal } = {}) {
  const queue = []; // 保存突发消息，避免消费者暂时忙碌时丢数据。
  let waiter = Promise.withResolvers();
  let closed = false;
  let failure;

  // 监听器只负责更新状态并唤醒当前等待器。
  const wake = () => waiter.resolve();
  const onMessage = (event) => {
    queue.push(event.data);
    wake();
  };
  const onClose = () => {
    closed = true;
    wake();
  };
  const onError = (event) => {
    failure = new Error("WebSocket 连接异常", { cause: event });
    closed = true;
    wake(); // 只唤醒消费者，避免生成器暂停在 yield 时产生未处理拒绝。
  };
  const onAbort = () => {
    failure = signal.reason ?? new DOMException("读取已取消", "AbortError");
    closed = true;
    wake(); // 实际错误由生成器在下一次读取时抛给调用方。
  };

  socket.addEventListener("message", onMessage);
  socket.addEventListener("close", onClose, { once: true });
  socket.addEventListener("error", onError, { once: true });
  signal?.addEventListener("abort", onAbort, { once: true });

  try {
    while (true) {
      if (failure) throw failure; // 错误优先于正常关闭交给调用方。
      if (queue.length > 0) {
        yield queue.shift(); // 每次只交付一条，保留异步迭代节奏。
        continue;
      }
      if (closed) return; // 队列清空后才完成正常关闭。

      await waiter.promise; // 没有缓存消息时等待下一次外部事件。
      waiter = Promise.withResolvers(); // 每次唤醒后更换新的等待器。
    }
  } finally {
    // 消费者 break、异常或取消时都释放监听器。
    socket.removeEventListener("message", onMessage);
    socket.removeEventListener("close", onClose);
    socket.removeEventListener("error", onError);
    signal?.removeEventListener("abort", onAbort);
  }
}

使用时，for await...of 就能以拉取式接口消费外部推送：

// 消费者可以在业务条件满足时 break，生成器的 finally 会执行清理。
for await (const message of websocketMessages(socket, {
  signal: controller.signal,
})) {
  handleMessage(message); // 业务处理与事件接线保持分离。
}

解析器的权限边界比语法更重要

resolve 和 reject 本质上是改变异步状态的能力。把它们放进全局变量、公共对象或跨团队共享的上下文，会让任意模块都能提前完成、伪造失败或掩盖真实事件。更稳妥的约束是：

• 解析器只保存在事件适配器的闭包内，对外暴露 promise、异步迭代器或受限的 close()。
• 每个桥接器明确唯一的成功事件、失败事件和关闭事件，不让多个来源随意竞争。
• 所有结算路径都执行同一套清理，避免事件监听器、超时任务和大对象引用长期存活。
• 持续事件必须有队列容量策略。上面的示例强调结构，真实高吞吐场景还要设置上限、丢弃策略或背压协议。

兼容回退不要改变调用契约

如果目标环境可能没有原生方法，可以在应用入口做一次特性检测。回退函数仍返回相同的三个字段，让业务代码不需要分支：

// 入口层统一能力检测，业务模块只依赖相同返回结构。
const createResolvers = typeof Promise.withResolvers === "function"
  ? () => Promise.withResolvers()
  : () => {
      let resolve;
      let reject;
      const promise = new Promise((res, rej) => {
        resolve = res;
        reject = rej;
      });
      return { promise, resolve, reject }; // 保持与原生方法相同的字段名。
    };

这个轻量回退只覆盖本文的原生 Promise 用法；如果项目依赖 Promise 子类或更复杂的构造器泛型行为，应采用经过项目测试的 polyfill，并验证子类构造签名。不要把一个只为普通 Promise 编写的帮助函数宣称为完整标准实现。

日志只记录生命周期，不记录敏感载荷

事件桥接出现“永远不结束”“偶发提前完成”时，需要可观测性。建议记录桥接器名称、创建时间、结算类型、耗时、超时与取消原因类别；WebSocket 桥接还可记录队列长度和丢弃计数。不要默认记录完整消息、身份令牌、URL 查询参数或用户输入。

哪些场景适合，哪些不适合

发布前检查清单

1. 目标环境是否支持原生方法，旧环境是否走统一回退。
2. 成功、失败、关闭、取消和超时是否都会释放监听器与定时器。
3. Promise 是否只负责一次结算，持续事件是否有独立队列。
4. 队列是否有限制，慢消费者策略是否明确。
5. resolve 与 reject 是否只存在于适配器内部。
6. 日志是否能定位生命周期，同时避开敏感事件载荷。

小结：Promise.withResolvers() 的价值不是替代所有 new Promise()，而是让外部事件驱动的完成入口与 Promise 处于同一、可控的作用域。一次性事件要做好取消和清理；持续事件要配合新等待器、显式队列、错误通道和容量策略。满足这些条件时，它会让事件桥接更平直，也更容易审计。