Promise.withResolvers 是为解决多源异步事件共同驱动状态变迁的工程问题而设计，它将 Promise 实例与决议能力解耦，支持安全、可拼装、可扩展的状态出口管理。
Promise.withResolvers 不是用来“简化状态机设计”的语法糖，而是解决一个具体工程问题：当状态变迁由多个不相关、不同时间点触发的异步回调共同驱动时，如何安全、解耦地把分散的 resolve/reject 调用统一注入到同一个 Promise 生命周期中。
为什么传统 new Promise() 在状态机里容易失控
在多事件源、多条件分支的状态流转中（比如“等待用户点击 OR 超时 OR 后端推送”），硬塞进 new Promise() 的 executor 会导致：
- 逻辑耦合：所有触发路径必须挤在一个函数体里，哪怕它们来自完全不同的模块或事件监听器
- 错误处理断裂：
reject可能散落在setTimeout、addEventListener、WebSocket.onmessage三个地方，但.catch()只能挂一次，漏掉任意一处就变成 silent pending - 无法动态增删条件：比如初始只监听点击，运行中又追加一个“收到特定 message 也应结束”，
new Promise()的 executor 已执行完毕，无法再介入
用 withResolvers 实现可拼装的状态出口
核心是把 Promise 实例和决议能力拆开，让状态机各分支只关心“该不该结束”，不关心“怎么结束”：
-
promise是只读引用，可安全传给消费者、存入 Map、作为返回值暴露 -
resolve和reject是独立函数，可封装成方法、绑定到对象、甚至按条件导出给外部模块 - 每个状态分支只需调用一次
resolve(value)或reject(error)，后续调用自动被忽略（符合 Promise A+）
示例：一个支持“手动跳过”“超时失败”“服务端确认”的三出口状态机
const { promise, resolve, reject } = Promise.withResolvers();
// 出口1：用户主动跳过
document.getElementById('skip-btn')?.addEventListener('click', () => {
resolve({ status: 'skipped', reason: 'user' });
});
// 出口2：10秒超时
const timeoutId = setTimeout(() => {
reject(new Error('timeout'));
}, 10000);
// 出口3：后端推送完成
const onMessage = (e) => {
if (e.data.type === 'task-completed') {
clearTimeout(timeoutId);
resolve({ status: 'completed', data: e.data.payload });
}
};
window.addEventListener('message', onMessage);
// 状态机使用者只消费 promise
export const taskFlow = promise.finally(() => {
window.removeEventListener('message', onMessage);
});
跨模块协作时 resolve/reject 的暴露边界
直接把 resolve 和 reject 暴露给外部模块风险高，推荐分层封装：
- 只导出
promise给调用方 —— 它只能消费，不能干扰 - 对内部模块提供带校验的封装函数，比如
completeTask(result)内部检查是否已决议，再调用resolve - 对外部可信模块（如测试工具）可导出
forceReject，但命名要明确其副作用，避免误用 - 永远不要把
resolve/reject存入全局变量或未清理的闭包 —— 这会阻止 GC，尤其在单页应用频繁切换场景下
兼容性 fallback 必须处理的两个细节
在 Node.js 18 或旧版浏览器中，Promise.withResolvers 会报 TypeError: Promise.withResolvers is not a function。手写 fallback 时注意：
- executor 必须立即执行，否则
resolve/reject可能为undefined导致后续调用崩溃 - 要手动捕获 executor 中抛出的异常并传给
reject，否则错误会冒泡到全局，而不是进入 Promise rejection 流程
最小可用 fallback：
function withResolvers() {
let resolve, reject;
const promise = new Promise((r, j) => {
resolve = r;
reject = j;
});
return { promise, resolve, reject };
}
真正难的不是写出能跑的代码，而是判断哪些状态分支该归入同一个 promise 生命周期 —— 比如“用户取消”和“网络失败”是否算同一类终止条件，这决定了你 resolve/reject 的语义粒度，也直接影响下游 .catch() 的错误分类逻辑。
