Promise.withResolvers() 是专为延迟控制 Promise 状态且隔离 resolve/reject 的场景设计的 API，返回含 promise、resolve、reject 的解构对象，适用于封装事件监听、可取消异步操作等；它不替代 new Promise()，不简化状态逻辑，仅提升声明安全与作用域隔离。
Promise.withResolvers 是什么，什么时候该用它
它不是用来替代 new Promise() 的通用方案，而是专为“需要延迟 resolve/reject 且不想暴露 resolve 和 reject 函数给外部”的场景设计。比如封装一个可手动触发完成的异步任务、实现超时取消逻辑、或桥接回调式 API（如 setTimeout、addEventListener）时，你不再需要自己声明并维护两个变量来存 resolve 和 reject。
常见错误是把它当成语法糖去“简化写法”，结果反而让控制流更难追踪——它只简化声明和隔离，不简化状态管理逻辑。
怎么用：基本结构与典型模式
Promise.withResolvers() 返回一个对象，含 promise、resolve、reject 三个属性。关键在于：这三个值从同一调用中产出，天然配对，避免闭包污染或引用丢失。
const { promise, resolve, reject } = Promise.withResolvers();
<p>// 后续可在任意地方调用 resolve() 或 reject()
setTimeout(() => resolve('done'), 100);</p><p>// 外部只消费 promise
return promise;</p>使用场景包括：
- 封装一次性事件监听：
addEventListener(..., handler, { once: true })触发后调用resolve - 实现带取消能力的延时器：在
clearTimeout时调用reject并附带AbortError - 测试中模拟异步响应：测试代码直接调用
resolve或reject，无需 mock 定时器
注意：不能多次调用 resolve 或 reject —— 和原生 Promise 一样，后续调用会被忽略，但不会报错，这点容易被忽略导致调试困难。
和 new Promise() 对比：差异在哪，坑在哪
最核心区别是作用域隔离：
-
new Promise((resolve, reject) => {...})中，resolve/reject只能在 executor 内访问；想外部触发就得把它们挂到对象上或用闭包暴露，易出错 -
Promise.withResolvers()直接返回解构友好的三元组，promise可立即返回，resolve/reject可安全传给其他函数或保存在实例字段里
性能上无差异，底层都是同一个 Promise 构造机制；兼容性目前仅 Chrome 121+、Firefox 126+、Node.js 21.7+ 支持，Safari 尚未支持，生产环境需检查或降级。
容易踩的坑：
- 把
{ promise, resolve, reject }解构后只保留promise，却忘了保存resolve引用，导致无法触发完成 - 在
try/catch外部调用reject，抛出未捕获异常（因为 Promise 拒绝未被处理） - 误以为它能“重置” Promise：一旦
resolve或reject被调用，promise状态就固化，不能再变
实际例子：封装一个可取消的 fetch 请求
function cancellableFetch(url, signal) {
const { promise, resolve, reject } = Promise.withResolvers();
<p>const controller = new AbortController();
signal?.addEventListener('abort', () => {
controller.abort();
reject(new DOMException('Aborted', 'AbortError'));
});</p><p>fetch(url, { signal: controller.signal })
.then(resolve)
.catch(err => {
if (err.name !== 'AbortError') reject(err);
});</p><p>return promise;
}</p>
这里 resolve 和 reject 被分别用于 fetch 成功/失败路径，而 abort 事件触发时也能精准调用 reject，所有分支共用同一套状态出口。比起手写闭包变量，逻辑更内聚，也更容易单元测试——你可以直接传入 mock 的 resolve 来验证流程。
真正麻烦的从来不是怎么写出来，而是确保所有可能的退出路径都覆盖到了，尤其是错误分支和中断信号。用 Promise.withResolvers() 不会自动帮你做这件事，只是让这件事更容易被组织清楚。
