网络请求、文件读取和计时器都会稍后完成，但 JavaScript 不能简单地停止和等待，否则页面会冻结。 JavaScript Promise 为您提供了一种简洁的方式来表达“当此操作完成时，执行此操作，如果失败，则执行此操作”。

即使您主要编写 async 和 await，您也会在下面使用 Promise，因此理解它们会使调试变得更加容易。我们在 Node.js 24 上运行这些示例，显示的输出来自该运行。它们在现代浏览器中的行为方式相同。

什么是承诺？

承诺是未来值的占位符。想象一下当你点餐时餐馆递给你的蜂鸣器。你还没有拿到食物，但你拿着一些东西，它会告诉你食物何时准备好，或者有问题，同时你可以自由地做其他事情。

在代码中，异步函数立即返回一个承诺，然后您附加接下来应该发生的事情：

fetch("/api/user")
  .then((response) => response.json())
  .then((user) => console.log(user.name))
  .catch((error) => console.log("Failed:", error.message));

三个承诺状态

履行或拒绝的承诺称为已解决。承诺只能解决一次。之后，它的状态和值就固定了，以后对 resolve 或 reject 的调用将被忽略。

创造一个承诺

您通常会使用 fetch 等 API 中的 Promise，但创建一个 Promise 会显示它们是如何工作的。构造函数接收两个函数，resolve 和 reject：

function fetchUser(id) {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (id > 0) {
        resolve({ id, name: "Asha" });
      } else {
        reject(new Error("Invalid id"));
      }
    }, 100);
  });
}

console.log(fetchUser(1));

// Promise { <pending> }

立即记录承诺表明它仍处于待处理状态，因为计时器尚未触发。该值只能通过处理程序或 await 访问。始终使用 Error 对象而不是字符串来拒绝，因为 Error 带有有助于调试的堆栈跟踪。

然后，抓住，最后

这三个方法将处理程序附加到 Promise：

fetchUser(1).then((user) => console.log(user.name));
// Asha

fetchUser(-1)
  .then((user) => console.log("never runs", user))
  .catch((error) => console.log("caught:", error.message))
  .finally(() => console.log("finally"));

// caught: Invalid id
// finally

then 成功时运行，catch 失败时运行，finally 两种情况都运行。这使得 finally 成为清理的正确位置，例如隐藏加载旋转器。它不会收到任何争论，因为它不应该关心结果。

连锁承诺

关键思想是 then 总是返回一个 新的 Promise。无论你的处理程序返回什么，都会成为新承诺的值：

Promise.resolve(2)
  .then((n) => n * 10)
  .then((n) => n + 1)
  .then((n) => console.log("chain:", n));

// chain: 21

如果处理程序返回另一个 Promise，链会等待它稳定下来，然后再继续。这就是将嵌套回调转变为扁平步骤序列的原因：

getUser(id)
  .then((user) => getOrders(user.id))
  .then((orders) => getInvoice(orders[0].id))
  .then((invoice) => console.log(invoice.total))
  .catch(handleError);

错误如何通过链条传播

被拒绝的 Promise 会跳过每个 then，直到到达 catch。将其扔进处理程序内也算作拒绝。正常返回的 catch 使链回到正轨：

Promise.resolve("start")
  .then(() => {
    throw new Error("step 2 failed");
  })
  .then(() => console.log("skipped"))
  .catch((error) => {
    console.log("caught:", error.message);
    return "recovered";
  })
  .then((value) => console.log("continues:", value));

// caught: step 2 failed
// continues: recovered

将此视为 try 和 catch 的异步版本。末尾的一个 catch 通常覆盖整个链。如果您只想记录错误但仍然失败，请从 catch 内部再次抛出它。

Promise.all、allSettled、race 和 any

这些静态方法同时协调多个 Promise。它们都接受一个数组并返回一个承诺。

为了测试它们，我们使用了两个小助手，一个在延迟后成功，另一个在延迟后失败：

const wait = (ms, value) =>
  new Promise((resolve) => setTimeout(() => resolve(value), ms));
const fail = (ms, message) =>
  new Promise((_, reject) => setTimeout(() => reject(new Error(message)), ms));

Promise.all

await Promise.all([wait(300, "a"), wait(100, "b"), wait(200, "c")]);

// [ 'a', 'b', 'c' ]   took about 300 ms

有两个细节需要注意。结果保持输入顺序，即使 b 首先完成。总时间约为 300 毫秒，这是最慢任务的时间，而不是 600 毫秒的总和，因为这三个任务已经同时运行。如果其中任何一个拒绝，整个事情就会立即拒绝：

await Promise.all([wait(100, "a"), fail(50, "b failed")]);

// rejected: b failed

Promise.allSettled

这会等待一切并报告每个结果，因此一次失败不会丢失其余的结果。它适合每个小部件独立加载的仪表板：

const results = await Promise.allSettled([wait(50, "a"), fail(50, "b failed")]);
results.map((r) => r.status);

// [ 'fulfilled', 'rejected' ]

Promise.race 和 Promise.any

await Promise.race([wait(300, "slow"), wait(100, "fast")]);   // fast
await Promise.any([fail(50, "x"), wait(100, "ok")]);          // ok

不同之处在于，race 会先解决，即使它失败了，而 any 只要成功，就会忽略失败。 race 的一个经典用法是为缓慢的请求添加超时，尽管较慢的任务会继续在后台运行，除非您取消它。

Promise 和 async/await

async 和 await 是使用相同 Promise 的更易读的方式。 async 函数总是返回一个 Promise，而 await 会暂停该函数，直到 Promise 解决：

async function showInvoice(id) {
  try {
    const user = await getUser(id);
    const orders = await getOrders(user.id);
    console.log(orders.length);
  } catch (error) {
    console.log("Failed:", error.message);
  }
}

拒绝会变成抛出错误，因此普通的 try 和 catch 可以工作。您仍然需要 Promise.all 来进行并行工作，因为等待一个又一个调用会按顺序运行它们。我们的 JavaScript async/await 指南对此进行了更深入的探讨。

Promise 和事件循环

即使承诺已经解决，承诺处理程序也不会立即被调用。它们在当前代码完成之后、任何计时器之前运行。这是证明：

setTimeout(() => console.log("timeout"), 0);
Promise.resolve().then(() => console.log("microtask"));
console.log("sync");

// sync
// microtask
// timeout

同步代码首先运行。接下来是微任务队列，它保存 Promise 处理程序。只有这样，事件循环才会开始执行下一个任务，例如计时器。这是一个流行的面试问题，它解释了为什么 setTimeout 为零并不是真正立竿见影的。

Promise 与回调

常见错误

• 忘记返回内部then。如果没有return，下一步将收到undefined，并且不会等待您内心的承诺。
• 根本没有catch。 这会导致未处理的拒绝，并且在 Node.js 中默认停止该进程。
• 嵌套而不是链接。将then放入then中会重新创建回调地狱。返回承诺并继续链条。
• 在new Promise中包装一个promise。如果一个函数已经返回一个promise，那么就使用它。
• 将forEach与异步回调结合使用。它不会等待。将 for...of 或 Promise.all 与 map 结合使用，如我们的 JavaScript 数组方法指南 中所示。
• 认为 Promise 可以取消。 它本身不能取消。对于请求，请使用 AbortController。

最后的话

Promise 归结为一些规则：promise 一次解决，then 返回一个新的 Promise，错误沿着链向下传播，直到有东西捕获它们。一旦这些规则感觉很自然，async 和 await 就不再那么神奇了。为了练习，使用 Promise 重写一个基于回调的函数，然后使用 Promise.all 获取两个端点并正确处理失败。

常见问题

继续学习