Promise 是什么

Promise 是 JavaScript 中表示「一个异步操作的最终结果」的对象。 它把「将来才会拿到的值」包装成一个可以等待、可以链式处理的对象,让异步代码像同步代码一样从上往下书写,避免层层嵌套的回调地狱(callback hell)。

一句话:Promise 是结果的占位符——现在还没有值,但未来一定会以「成功」或「失败」两种方式之一给出答复,并且只答复一次。

状态 含义 如何进入
pending(待定) 初始状态,结果还没出来 新建 Promise 时
fulfilled(已兑现) 成功,携带一个结果值 调用 resolve(value)
rejected(已拒绝) 失败,携带一个原因(通常是 Error) 调用 reject(reason),或执行器内抛错

两条铁律:

  • 状态只能改变一次。一旦从 pending 落到 fulfilled 或 rejected,就永久固定,之后再调用 resolve / reject 都不会生效。
  • 状态不可逆。成功不会变失败,失败也不会变成功。

new Promise(executor) 接收一个执行器函数,执行器会立即同步执行,其中拿到 resolve 和 reject 两个参数:

function delay(ms: number): Promise<void> {
  return new Promise<void>((resolve) => {
    setTimeout(() => resolve(), ms);
  });
}
 
function fetchUserName(id: number): Promise<string> {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (id > 0) {
        resolve('用户' + id);        // 成功,结果向下传递
      } else {
        reject(new Error('无效的用户 ID'));  // 失败
      }
    }, 100);
  });
}

平时更常见的做法是直接返回别人给的 Promise(例如 fetch、数据库驱动、SDK 的异步方法),只有包装回调风格的旧 API 时才需要自己 new Promise。

  • .then(onFulfilled, onRejected):成功走第一个回调,失败走第二个(一般省略第二个,统一交给 catch)。
  • .catch(onRejected):捕获链上任意位置的失败,等价于 .then(undefined, onRejected)。
  • .finally(onFinally):无论成功失败都会执行,常用于清理(关闭 loading、释放连接)。回调不接收参数,返回值不影响后续结果(除非它抛出异常)。
fetchUserName(1)
  .then((name) => console.log('成功:', name))
  .catch((err) => console.error('失败:', err.message))
  .finally(() => console.log('结束,关闭 loading'));

这是 Promise 最关键的机制:

  • 回调返回普通值 → 下一个 .then 收到这个值;
  • 回调返回另一个 Promise → 会等它完成,再把结果传给下一个 .then(自动「解包」,不会出现 Promise 套 Promise);
  • 回调抛出异常 → 跳过后续所有 then,直达最近的 catch。
interface User {
  id: number;
  name: string;
}
 
function getUser(id: number): Promise<User> {
  return Promise.resolve({ id, name: '张三' });
}
 
function getOrders(userId: number): Promise<string[]> {
  return Promise.resolve(['A1', 'A2']);
}
 
getUser(1)
  .then((user) => getOrders(user.id))        // 返回 Promise,链会等它
  .then((orders) => {
    if (orders.length === 0) throw new Error('没有订单'); // 主动抛出,走 catch
    return orders[0];                        // 返回普通值,继续向下传
  })
  .then((orderId) => console.log('订单号', orderId))
  .catch((err: Error) => console.error(err.message));

忘记 return 是最常见的 bug:若箭头函数体用了大括号却只调用不返回,下一个 .then 收到的是 undefined,而且整条链也不会等待请求完成。错误写法形如 .then(user => { getOrders(user.id); }) (大括号里没有 return),正确写法是 .then(user => getOrders(user.id)) 。

方法 作用 结果
Promise.resolve(v) 把值包装成成功的 Promise 单个值
Promise.reject(e) 直接创建一个失败的 Promise 失败原因
Promise.all(list) 全部成功才成功,任一失败立即失败 结果数组(顺序与输入一致)
Promise.allSettled(list) 等全部结束,无论成败 {status, value/reason} 数组
Promise.race(list) 第一个结束的(无论成败) 那个值或原因
Promise.any(list) 第一个成功的,全部失败才失败 那个值(AggregateError)
// 并发执行,全部成功才继续;任一失败直接进 catch
const [user, orders] = await Promise.all([getUser(1), getOrders(1)]);
 
// 允许部分失败,逐条检查结果
const results = await Promise.allSettled([getUser(1), getOrders(-1)]);
 
// 超时控制:让「超时」与「真实请求」赛跑
function withTimeout<T>(task: Promise<T>, ms: number): Promise<T> {
  const timeout = new Promise<never>((_, reject) =>
    setTimeout(() => reject(new Error('请求超时')), ms)
  );
  return Promise.race([task, timeout]);
}

注意 Promise.all 是并发而不是顺序:需要按依赖顺序执行时,必须用 then 链或用 await 一条条写。

async / await 是 Promise 的语法糖,底层仍然是 Promise:

  • async 函数一定返回 Promise;返回普通值会自动包成 Promise.resolve(值)。
  • await 遇到 Promise 会等待其落定:成功则拿到值,失败则以抛异常的方式从 await 处抛出。
  • 因此用 await 时错误要用 try / catch 捕获(见 什么是try_catch),而不是 .catch。
async function loadOrderId(id: number): Promise<string | null> {
  try {
    const user = await getUser(id);
    const orders = await getOrders(user.id);   // 串行:需要上一步结果
    return orders[0] ?? null;
  } catch (err) {
    console.error((err as Error).message);
    return null;
  }
}
 
// 无依赖关系的任务应该并发,而不是串行 await
async function loadBoth(id: number) {
  const [user, orders] = await Promise.all([getUser(id), getOrders(id)]);
  return { user, orders };
}

Promise<T> 的类型参数 T 就是成功值的类型;失败值(reject 的原因)在标准库中没有类型参数,通常当作 unknown 处理,用 instanceof Error 或类型守卫收窄。

const p: Promise<number> = Promise.resolve(1);
 
// 可调用的 Promise:类型是函数,返回值是 Promise
type AsyncHandler = () => Promise<void>;
 
// 注意不要写成 Promise<Promise<T>>,async 函数已被自动展平
async function ok(): Promise<string> {
  return 'ok';
}
  • 忘了 return:链不等待,后续拿到 undefined。
  • 在 forEach 里写 async:forEach 不会等待回调,循环立刻结束。改用 for…of + await,或 Promise.all(list.map(…))。
  • 未处理的 rejection:没有 catch 的失败 Promise 会触发 unhandledrejection,在 Node 中可能导致进程退出。
  • 多余的 new Promise 包装:已有 Promise 时直接 return 它,不要套一层。
  • 在 then 里继续写回调风格:容易丢错误,尽量统一成 Promise 风格。
  • 把串行当并发:连续 await 是串行,无依赖时用 Promise.all 并行更快。

Promise = 异步结果的状态容器 + 可链式传递的错误通道。记住三点:状态只变一次、then 的返回值决定下一步、失败沿链传播直到被 catch。

# Promise
## 是什么
- 异步结果的占位符
- 解决回调地狱
- 状态只能改变一次
## 三种状态
- pending 待定
- fulfilled 已兑现
- rejected 已拒绝
## 创建
- new Promise(executor)
- 执行器同步执行
- resolve / reject
## 消费
- then 处理成功
- catch 处理失败
- finally 收尾清理
## 链式调用
- 返回普通值继续传
- 返回 Promise 自动等待
- 抛异常跳到 catch
- 忘记 return 拿到 undefined
## 静态方法
- all 全部成功
- allSettled 等全部结束
- race 第一个结束
- any 第一个成功
## async await
- async 必返回 Promise
- await 等待落定
- 错误用 try catch
- 无依赖改用 Promise.all
## 常见坑
- forEach 里写 async
- 未处理 rejection
- 串行当并发

该主题尚不存在

您访问的页面并不存在。如果允许,您可以使用创建该页面按钮来创建它。

  • typescript/什么是promise.txt
  • 最后更改: 2026/10/27 10:29
  • 由 张叶安