一个在 forEach 回调里写 await 的批处理脚本,以为会一个个等着处理完,结果还没处理完就往下走、还吞掉了异常:一次 JavaScript 异步遍历的深度复盘

那个 bug 是一个数据迁移脚本暴露的:我要把一批用户记录逐条调接口同步到新系统,处理完后打印一句"全部同步完成"。我很自然地用 forEach 遍历数组、在回调里 await 每条记录的同步。可运行后,问题接二连三:那句"全部同步完成"几乎是立刻就打印出来了——可此时记录根本还没同步完;而且我在外层用 try-catch 包着,某条记录同步失败抛了异常,catch 却一个都没抓到,异常变成了刺眼的 UnhandledPromiseRejection。我盯着这段"看起来很合理"的 forEach + await 看了半天,才终于明白问题所在,后背发凉:Array.prototype.forEach 根本不理会你回调函数返回的 Promise——它不会等待你 await 的异步操作完成,就径直地、同步地把所有元素都"过"了一遍。也就是说,我在 forEach 回调里写 async,只是飞快地、几乎同时地启动了所有记录的同步操作(每个都返回一个没人等的 Promise),然后 forEach 立刻就结束了、外层代码立刻往下走、打印了"完成"——可那些异步操作其实都还在后台跑着。而那些回调返回的 Promise 无人 await、无人处理,其中失败的那个,它的 rejection 就没有任何 catch 能接住,成了未处理的拒绝。这篇就把这次"forEach 里用 await 无效"的坑,从头到尾复盘一遍。

故障现场:在 forEach 回调里 await

问题代码,是一个几乎人人都写过的"异步遍历":

// ✗ 出问题的代码: 在 forEach 回调里 await
async function syncAll(records) {
  try {
    records.forEach(async (record) => {     // ✗ forEach 不会等待这个async回调!
      await syncOne(record);                // 每条记录调接口同步(异步)
    });
    console.log("全部同步完成");             // ✗ 这句几乎立刻打印, 此时根本没同步完!
  } catch (e) {
    console.error("同步失败", e);            // ✗ 抓不到syncOne抛的异常!
  }
}

// 发生了什么:
// 1. forEach 遍历数组, 对每个元素调用那个 async 回调;
// 2. 但 forEach 【根本不看回调的返回值(Promise)】, 它不会await、不会等;
//    → 它只是飞快地、几乎同时地"启动"了所有 syncOne(record), 每个返回一个Promise;
// 3. forEach 立刻"遍历完"返回 → 代码立刻走到 console.log("全部同步完成");
//    → 可此时那些 syncOne 还都在后台异步跑着, 一条都没完成!
// 4. 那些回调返回的Promise【无人await、无人catch】;
//    → 如果某个 syncOne reject(失败), 它的rejection没有任何catch接住
//    → UnhandledPromiseRejection(外层try-catch包不住, 因为forEach早就同步返回了)。

// 根本原因:
// - forEach 的设计就是【同步】遍历, 它【忽略回调的返回值】, 对Promise一无所知;
// - 在它的回调里写async/await, await只在【那个回调内部】生效, forEach本身不会等。

// 关键: forEach 不支持异步等待; 在它回调里await不会让forEach等待, 会导致"没等完就继续"
//       和"异常无人处理"。想顺序/并发地等异步, 不能用forEach。

第一次想通时,我又懊恼又恍然:"我明明在回调里 await 了,怎么 forEach 就不等呢?"这个坑最隐蔽的地方在于:它看起来太合理了——forEach 是最常用的遍历,await 是等异步的标准写法,两个都对的东西拼在一起,谁会怀疑?可它们根本不兼容:forEach 是为同步设计的、无视回调返回的 Promise。而且它不会报语法错(async 回调完全合法),只是行为不符预期:没等完就继续、异常无人处理——这种"能跑、不报错、但行为错"的坑,最容易让人栽进去。下面就来拆解,为什么 forEach 不能等异步、该用什么。

第一件事:搞懂 forEach 为什么不等异步,以及该用什么

我认真梳理了 JS 的异步遍历,才彻底理解这个坑和正确的做法。

forEach 为什么不等异步? 异步遍历该用什么?

【核心: forEach是同步遍历、忽略回调返回的Promise; 要等异步, 用for...of+await(顺序)或Promise.all(并发)】

1. forEach 为什么不等:
   - forEach 的设计是【同步遍历】: 它依次调用回调, 但【完全忽略回调的返回值】;
   - 你的async回调返回的是一个Promise, forEach对它视而不见、不会await;
   - → 它飞快地"启动"了所有异步操作(发出去就不管), 自己立刻同步返回;
   - → 结果: "没等异步完成"就继续了; 回调的Promise无人处理, reject就成未处理拒绝。

2. 想"一个个顺序等"——用 for...of + await:
   for (const record of records) {
     await syncOne(record);     // ★ 这个await真正会暂停循环, 等这条完成再下一条
   }
   // → for...of循环体里的await, 会真正让循环【顺序地、一个等一个地】执行; 异常也能被外层try-catch抓到。

3. 想"全部并发, 一起等"——用 Promise.all + map:
   await Promise.all(records.map(record => syncOne(record)));
   // → map把每个record变成一个Promise(同时启动, 并发), Promise.all等它们【全部完成】;
   //   比顺序快(并发); 但要注意并发量, 太多可能压垮下游(可用分批/p-limit限并发)。

4. 顺序 vs 并发, 怎么选:
   - 要保证顺序、或后一个依赖前一个、或要限制并发 → for...of + await(顺序);
   - 各项独立、想快、下游扛得住并发 → Promise.all(并发);
   - 折中: 分批并发(每批N个Promise.all, 批与批之间顺序)。

5. 异常处理:
   - for...of+await: 异常会从await抛出, 外层try-catch能正常抓;
   - Promise.all: 任一个reject, Promise.all就reject(可被await的try-catch抓);
     (要"不因一个失败而中断全部", 用Promise.allSettled)。

一句话: forEach是同步遍历、无视回调的Promise, 不能用来等异步; 顺序等用for...of+await、
   并发等用Promise.all+map; 它们才能真正等待异步完成、并让异常被正常捕获。

这套认知,是整个坑的根。forEach 为什么不等:它的设计是同步遍历、完全忽略回调的返回值,你的 async 回调返回的 Promise 它视而不见、不会 await,于是飞快"启动"所有异步操作就立刻同步返回——"没等异步完成"就继续了、回调的 Promise 无人处理。想顺序等用 for...of + await(循环体里的 await 真正暂停循环、一个等一个、异常能被外层 try-catch 抓);想并发等用 Promise.all + map(map 把每项变成 Promise 同时启动、Promise.all 等全部完成、更快但要注意并发量)。顺序 vs 并发怎么选?要顺序/有依赖/限并发→for...of+await;各项独立想快下游扛得住→Promise.all;折中用分批并发。异常处理:for...of+await 异常从 await 抛出能被 try-catch 抓;Promise.all 任一 reject 就 reject(要不中断全部用 allSettled)。一句话:forEach 是同步遍历、无视回调的 Promise,不能等异步;顺序等用 for...of+await、并发等用 Promise.all+map;它们才能真正等待异步完成、并让异常被正常捕获。

第二件事:正解——顺序用 for...of+await,并发用 Promise.all+map

搞懂了原理,正解就清晰了:要顺序处理用 for...of + await;要并发处理用 Promise.all + map;需要限并发就分批或用并发控制库;按是否要顺序、下游能否扛并发来选。

// ====== 正解一: 顺序处理(一个等一个), 用 for...of + await ======
async function syncSequential(records) {
  try {
    for (const record of records) {
      await syncOne(record);          // ★ 真正等这条完成, 再处理下一条
    }
    console.log("全部同步完成");        // ✓ 现在这句确实在全部完成后才打印
  } catch (e) {
    console.error("同步失败", e);       // ✓ 异常能被正常抓到
  }
}
// → 适合: 要保证顺序、后一个依赖前一个、或要严格限制对下游的并发压力。

// ====== 正解二: 并发处理(一起跑, 一起等), 用 Promise.all + map ======
async function syncConcurrent(records) {
  try {
    await Promise.all(records.map(record => syncOne(record)));
    console.log("全部同步完成");        // ✓ 等所有并发的Promise都完成后才打印
  } catch (e) {
    console.error("有记录同步失败", e);  // ✓ 任一失败, Promise.all reject, 这里能抓到
  }
}
// → 适合: 各项独立、想要快、下游能扛住并发; 比顺序快很多。
// → 注意: records很多时, 这会同时发出成百上千个请求, 可能压垮下游!要限并发(见下)。

// ====== 正解三: 限并发(既要快又不压垮下游), 分批 或 用并发控制 ======
// 方式A: 分批并发(每批N个并发, 批与批之间顺序)
async function syncInBatches(records, batchSize = 10) {
  for (let i = 0; i < records.length; i += batchSize) {
    const batch = records.slice(i, i + batchSize);
    await Promise.all(batch.map(r => syncOne(r)));   // 每批10个并发
  }
}
// 方式B: 用 p-limit 等库控制最大并发数
// const limit = pLimit(10);
// await Promise.all(records.map(r => limit(() => syncOne(r))));

// ====== 正解四: 不想因一个失败而中断全部, 用 Promise.allSettled ======
const results = await Promise.allSettled(records.map(r => syncOne(r)));
const failed = results.filter(r => r.status === "rejected");
console.log(`成功${results.length - failed.length}, 失败${failed.length}`);
// → allSettled等所有完成(不管成功失败), 返回每个的结果, 不会因一个reject而中断。

// ====== 决策 ======
// - 要顺序/有依赖: for...of + await;
// - 要并发且下游扛得住: Promise.all + map;
// - 要并发但需限流: 分批 / p-limit;
// - 要"全部都跑、单独收集成败": Promise.allSettled。

// 核心: 别在forEach里await; 顺序用for...of+await、并发用Promise.all+map、限并发用分批/p-limit、
//   收集成败用allSettled; 按"是否要顺序、下游能否扛并发、如何处理失败"来选对的方式。

修复的核心,是"用真正能等待异步的遍历方式,并按场景选顺序还是并发"。正解一:顺序用 for...of + await——真正一个等一个,适合要顺序/有依赖/限并发压力;"完成"在全部完成后才打印,异常能被抓到。正解二:并发用 Promise.all + map——一起跑一起等,比顺序快;但 records 多时会同时发海量请求、可能压垮下游。正解三:限并发用分批或 p-limit(既快又不压垮下游)。正解四:不想因一个失败中断全部用 Promise.allSettled(等所有完成、单独收集成败)。归根结底:别在 forEach 里 await;顺序用 for...of+await、并发用 Promise.all+map、限并发用分批/p-limit、收集成败用 allSettled;按"是否要顺序、下游能否扛并发、如何处理失败"选对方式。

第三件事:JavaScript 异步相关的其他常见坑

排查后我把 JS 异步相关的其他常见坑也系统梳理了一遍。

JavaScript 异步的其他常见坑

# 1. forEach里await无效(本文): forEach不等异步。→ for...of+await / Promise.all。

# 2. 忘了await: 调async函数没await, 拿到的是Promise不是结果, 异常也丢。→ 别忘await。

# 3. 没catch的Promise: 漏掉.catch/try-catch → UnhandledPromiseRejection。→ 异步都要处理错误。

# 4. 不必要的串行: 本可并发的几个独立异步, 用await一个个串行做, 慢。→ 独立的用Promise.all并发。

# 5. await在map里以为并发但其实...: const r = arr.map(async x=>await f(x)) 是并发启动(返回Promise数组),
#    要await Promise.all(r)才拿结果; 别和for...of搞混。

# 6. Promise.all一个失败全失败: 任一reject整体reject。→ 要全跑完用allSettled。

# 7. 在循环里不限并发: 一次性发出成千上万异步请求压垮下游/自己。→ 限并发(分批/p-limit)。

# 8. 误解事件循环: setTimeout(0)不是立刻、微任务(Promise)优先于宏任务(setTimeout)。

# 共同根源: 没真正理解JS的异步模型(Promise、事件循环、哪些API支持/不支持异步等待);
#   把同步的思维和API(forEach)用在异步场景, 或不清楚顺序/并发/错误处理的正确写法。

# 核心: 理解Promise和事件循环; 异步遍历用for...of+await或Promise.all(别用forEach); 都要处理错误;
#   分清顺序与并发、按需限并发、用allSettled收集成败——写对异步控制流。

排查让我把 JS 异步的其他坑也梳理清了。一、forEach 里 await 无效(本文)。二、忘了 await(拿到 Promise 不是结果)。三、没 catch 的 Promise(UnhandledRejection)。四、不必要的串行(独立的用 Promise.all 并发)。五、map 里 async 的并发语义(要 Promise.all 才拿结果)。六、Promise.all 一个失败全失败(用 allSettled)。七、循环里不限并发。八、误解事件循环(微任务优先于宏任务)。它们的共同根源是:没真正理解 JS 的异步模型(Promise、事件循环、哪些 API 支持异步等待);把同步的思维和 API(forEach)用在异步场景,或不清楚顺序/并发/错误处理的正确写法。核心是:理解 Promise 和事件循环;异步遍历用 for...of+await 或 Promise.all(别用 forEach);都要处理错误;分清顺序与并发、按需限并发、用 allSettled 收集成败——写对异步控制流。下面这张图,是这次 forEach 异步坑的成因与解法:

第四件事:异步遍历方式选型速查表

这次踩坑后,我把几种"遍历+异步"的方式整理成一张表,按需求选。

这张表把异步遍历选型钉清了。核心是:处理"一批异步任务",关键先想两个问题——"要顺序还是可并发"(顺序用 for...of+await、并发用 Promise.all)和"失败了怎么办"(中断用 all、全跑用 allSettled);而 forEach 在异步场景里直接出局(它不等异步)。它给我的最大启发是:"遍历"这个看似简单的操作,在引入"异步"后,多出了好几个需要主动决策的维度——顺序还是并发?并发要不要限流?一个失败是中断还是继续?;这些在"同步遍历"里根本不存在的问题,在异步世界里都浮现出来,且每个选择都影响正确性和性能。这让我体会到异步编程的一个特点:异步把"时间"这个维度显式地引入了编程——同步代码里"一行接一行执行"是默认的、不用想的;而异步代码里,"什么时候执行、谁先谁后、要不要等、并行几个"都变成了需要你显式安排的事;"控制异步任务之间的时序和并发关系(异步控制流)",是异步编程区别于同步编程的核心难点和核心技能。掌握异步遍历的顺序/并发/失败处理选型、驾驭异步控制流——是这个坑带给我的认知。

第五件事:这个坑暴露的"API 是同步还是异步感知"

这次让我意识到,要分清哪些 API"感知 Promise"、哪些不感知。我整理成表。

这张表道出了一个容易被忽视的区别。核心是:JS 的数组方法/遍历写法,分成"感知 Promise、会等异步"和"无视 Promise、不等异步"两类——for...of+await、Promise.all、for await...of 能等;而 forEach、filter、reduce 这些为同步设计的方法,会无视回调返回的 Promise;在异步场景必须用前一类。它给我的深刻启发是:用任何 API,都要搞清楚它"是不是为异步设计的、会不会处理 Promise"——因为大量 API 是在"异步/Promise 还没普及或不在其设计目标内"时定义的,它们对 Promise 一无所知(forEach 就是),你把返回 Promise 的 async 函数传给它们,它们只会把 Promise 当成"一个普通返回值"丢掉;"这个 API 是否理解/等待异步",是用它处理异步时必须确认的一件事。这给了我一种使用 API 的细致:在异步代码里用一个 API 前,先确认"它认不认 Promise"——认的(返回 Promise、文档说支持异步、名字带 async/await)放心用;不认的(老的同步 API、文档没提异步)别指望它等你的异步,要换成感知异步的写法;"分清同步 API 和异步感知 API,在异步场景用对的那类",能避开一大类"它没等我的异步"的坑。分清 API 是否感知 Promise、在异步场景用对的那类——是这个 forEach 坑带给我的实用认知。

第六件事:要异步遍历一批数据时,我现在的判断习惯

现在每当我要对一批数据做异步处理,我都会按这张图先想清楚:

这张图的精髓,是"先定顺序还是并发,再定失败处理,绝不用 forEach"。先看有无顺序依赖(有→for...of+await、无→并发);并发看下游能否扛(扛得住→Promise.all、扛不住→限并发);再定失败是中断还是收集(all/allSettled);始终不用 forEach 做异步遍历。这套习惯,让我从"遍历就用 forEach"变成了"异步遍历先想顺序/并发/失败处理"——核心始终是:forEach 不等异步,异步遍历用 for...of+await 或 Promise.all,按顺序/并发/失败需求选。

我立下的几条规矩

这场"forEach 里 await 无效"的事故,换来了我写 JavaScript 异步时,刻进骨子里的几条铁律:

1. forEach 不等异步。它是同步遍历、忽略回调返回的 Promise,绝不用它做异步遍历。
2. 顺序处理用 for...of + await。循环体里的 await 真正暂停循环,一个等一个。
3. 并发处理用 Promise.all + map。一起跑一起等,比顺序快。
4. 并发量大要限流。分批或 p-limit,别一次性发海量请求压垮下游。
5. 不想因一个失败中断全部用 allSettled。等所有完成、单独收集成败。
6. 异步都要处理错误。别留没 catch 的 Promise,否则 UnhandledRejection。
7. 用 API 前确认它认不认 Promise。同步 API 不会等你的异步。

附:一个限并发的小工具

实战里"并发但限流"的需求最常见,我封装了一个不引依赖的限并发小工具,供团队复用。

// 限制最大并发数地处理一批任务(不引第三方库)
async function mapLimit(items, limit, asyncFn) {
  const results = [];
  const executing = new Set();
  for (const [i, item] of items.entries()) {
    const p = Promise.resolve(asyncFn(item, i)).then(r => { results[i] = r; });
    executing.add(p);
    p.finally(() => executing.delete(p));
    if (executing.size >= limit) {
      await Promise.race(executing);   // ★ 达到并发上限, 等最快的一个完成再继续
    }
  }
  await Promise.all(executing);         // 等剩余的全部完成
  return results;
}

// 用法: 最多10个并发地同步记录
await mapLimit(records, 10, record => syncOne(record));
// → 既享受并发的速度, 又把同时进行的请求数控制在10个以内, 不压垮下游。

这个小工具,把"并发但限流"这个高频又易写错的需求,封装成了一行 mapLimit。核心是:它用 Promise.race 在达到并发上限时"等最快的一个完成"再放进下一个,从而把同时进行的任务数稳定地控制在 limit 以内——既有并发的速度、又不会一次性发出海量请求压垮下游。它给我的启发是:"顺序(慢但稳)"和"全并发(快但可能压垮下游)"是两个极端,而实战中最常需要的, 恰恰是二者之间的"限并发"——"又要快、又要可控",往往不是选某个极端,而是在两个极端之间找一个可调的平衡点(并发度);把这个"平衡点"参数化(limit)、封装成可复用的工具,就能在不同场景下灵活地权衡速度与压力。用 mapLimit 把限并发封装成可调的平衡、在快与稳之间找平衡点——是这个坑教我的实用收尾。

写在最后

回头看,这场由"在 forEach 里 await"引发的、没等完就继续又吞异常的事故,真正教给我的,远不止"异步遍历别用 forEach"这一个技巧。它让我对"把两个各自正确、却互不兼容的东西拼在一起,会得到一个既不报错、又不正确的结果",有了一次刻骨的体会。我栽跟头,是因为我把两个各自都对的东西——"用 forEach 遍历"(对)和"用 await 等异步"(对)——想当然地组合在了一起,却没意识到这两者的"前提假设"是矛盾的:forEach 的前提是"回调是同步的、它不关心回调何时'真正'做完",而 await 的诉求恰恰是"我要等这个异步真正做完"——一个"不等"、一个"要等",根本合不到一起。我以为"对 + 对 = 对",可在它们前提冲突的地方,得到的是"能跑、但行为错"——这种错最隐蔽,因为组成它的每一块看起来都没问题。这让我领悟到一个关于"组合"的深刻认知:"正确的零件"不保证"正确的组合"——两个单独都正确的东西,组合起来是否正确,取决于它们的"契约/前提假设"是否相容;很多 bug 不在某个"错误的部件"里,而在"正确的部件之间,那个被忽视的、不匹配的接缝处";"它能编译/能跑"只说明每个部件语法上能拼上,不说明它们的语义/前提真的契合。这给了我一种组合代码时的警觉:把两个组件/API/特性组合使用时,不能只看它们各自对不对,还要想"它们的假设兼容吗?一个的输出/行为,正好是另一个期待的输入/前提吗?"——尤其当组合"同步的东西"和"异步的东西"、"老的 API"和"新的范式"时,这种接缝处的不匹配特别常见;"关注部件之间的接缝,而不只是部件本身",是排查和避免这类隐蔽 bug 的关键。认清正确的零件不保证正确的组合、关注部件接缝处的前提是否相容——这,是我用一次 forEach+await 的事故,换来的、关于 JavaScript、也关于如何正确组合代码的、最朴素也最深刻的领悟。如果这篇复盘,能让你下次想在 forEach 里写 await 时,顿一下、改成 for...of 或 Promise.all,那我对着那个"提前完成又吞异常"的脚本排查的这段时间,就值了。

—— 别看了 · 2026