JavaScript Promise.withResolvers 怎么管理外部 resolve：一次性完成、重复调用与资源清理

需要把一次浏览器事件、消息回调或超时结果交给一个 Promise 时，Promise.withResolvers 比手写外层变量更容易把职责分开：创建阶段拿到 Promise，触发阶段调用 resolve 或 reject，收尾阶段统一解除监听和计时器。它并不会自动帮你防止重复完成，也不会替你清理外部资源。

这个 API 解决的是“谁来完成 Promise”

传统写法会把 resolve 和 reject 声明在构造器外层，再通过 new Promise 捕获它们。代码一多，完成器的生命周期就容易和事件监听、超时句柄混在一起。Promise.withResolvers() 直接返回一个对象，三个字段的关系更清楚。

const { promise, resolve, reject } = Promise.withResolvers();

button.addEventListener('click', () => resolve('clicked'), { once: true });
setTimeout(() => reject(new Error('timeout')), 3000);

promise.then(value => console.log(value));

这里的重点不是少写几行，而是把“等待结果”和“产生结果”拆成两个位置。事件回调可以持有 resolve，调用方只消费 promise。

最小可用写法：给外部回调加一次性门禁

Promise 自己会忽略第二次状态变更，但外部回调里的副作用不会自动消失。例如第一次消息已经让界面关闭，第二次消息仍可能继续写日志、触发埋点或修改缓存。因此应显式记录是否已经完成。

function waitForMessage(channel, timeoutMs = 3000) {
  const { promise, resolve, reject } = Promise.withResolvers();
  let settled = false;
  let timer;

  const finish = (fn, value) => {
    if (settled) return;
    settled = true;
    clearTimeout(timer);
    channel.removeEventListener('message', onMessage);
    fn(value);
  };

  function onMessage(event) {
    finish(resolve, event.data);
  }

  channel.addEventListener('message', onMessage);
  timer = setTimeout(() => finish(reject, new Error('message timeout')), timeoutMs);
  return promise;
}

settled 保护的是资源和副作用，Promise 的单次状态规则只是最后一道保护。把清理放进同一个 finish 函数，成功、失败、超时都走同一条出口，后续修改不容易漏掉其中一路。

重复调用、异常和超时要分开判断

调用 resolve 后再调用 reject，Promise 不会变成 rejected；但如果 resolve 前的回调已经做了两次业务写入，问题依旧存在。门禁应放在副作用之前，而不是只依赖 Promise 的语义。

事件处理器内部如果可能抛出同步异常，应该在边界处捕获并交给 finish(reject, error)。超时也不是“再 resolve 一个默认值”，而是一个可观察的失败原因，调用方才能决定重试、提示或降级。

什么时候不该使用 withResolvers

如果逻辑只是把一个请求结果映射成另一个值，直接返回 fetch(...).then(...) 或使用 async/await 更容易追踪。withResolvers 适合“完成动作发生在另一个时间点、另一个回调或另一个模块”的场景，不适合把每个普通异步函数都改写成外部控制器。

• 单次事件、消息端口、回调式 SDK 适合使用，但要配套关闭监听。
• 多个结果需要持续产生时，应考虑 AsyncIterator 或事件流，不要反复复用同一个 Promise。
• 需要取消时，把 AbortSignal 作为输入，并在 abort 路径调用统一的 reject 和清理函数。

验证清单：看状态，也看资源

测试不只断言 Promise 最终值，还要确认完成后监听器和计时器确实被移除。至少覆盖首次成功、首次失败、超时后晚到消息、重复消息和取消五种情况。对重复消息，可以在测试回调里记录副作用计数，期望它始终为 1。

const result = await waitForMessage(channel, 50);
console.assert(result === expected);
// 发送第二条消息，副作用计数仍应保持 1

常见问题

Promise.withResolvers 会自动阻止重复 resolve 吗？

Promise 状态只接受第一次改变，但外部回调仍会继续执行。需要自己用 settled 标记保护业务副作用和资源清理。

它和 new Promise 的主要差别是什么？

两者都能创建 Promise，区别在于 withResolvers 直接把完成器作为返回对象暴露出来，更适合由外部事件完成结果；普通构造器更适合在创建函数内部立即描述异步过程。

为什么 finally 仍然重要？

完成器只负责改变 Promise 状态，不知道你注册了哪些监听器或计时器。finally 或统一出口函数可以把资源清理与成功、失败路径绑定起来。

把完成器当作一次性资源管理器

Promise.withResolvers 的价值在于边界清楚：外部事件负责发出结果，Promise 负责交付结果，统一出口负责保证只完成一次并释放资源。只要把门禁、超时、异常和清理写在同一条可检查的路径上，这个 API 就能简化事件桥接；如果只是普通链式异步，保持更直接的写法反而更稳。