日志说完成数据却没动:forEach 异步陷阱避坑复盘

那次事故的现象,一开始把我们整个团队都看懵了:一个跑批量数据处理的 Node.js 脚本,日志里明明白白打着"全部处理完成,共 5000 条",可数据库里实际被更新的,却总是只有零星几十条,而且每次跑数量还不一样。更诡异的是,脚本没报任何错,退出码是 0,一副"我成功了"的样子。一个声称自己"全部完成"、还没报错的程序,干的活却只有它声称的零头——这种"嘴上说着完成了、手上啥也没干完"的诡异,排查起来格外让人抓狂,因为你连个错误堆栈都没有,无从下手。

查到最后,根因让我对 JavaScript 的异步模型有了一次脱胎换骨的理解。问题出在一行几乎每个 JS 开发者都写过、看起来无比正确的代码上:array.forEach(async item => { await process(item) })。我们想当然地以为,加了 async 和 await,这个 forEach 就会乖乖地等每一条都处理完;可真相是——forEach 根本不认识、也根本不会去等 async 回调返回的那个 Promise,它头也不回地把 5000 个异步任务"点了火"就立刻返回了,后面那句"全部处理完成"在绝大多数任务还在天上飞的时候,就抢先打印出来了。这篇文章,就从这次"嘴上说完成、手上没干完"的事故讲起,把 JavaScript 异步编程里这些最违反直觉、却又最高频的坑,一个个讲透。

故障现场:一个"撒谎"的批处理脚本

先把那段闯祸的代码还原出来,它简化后长这样:

async function migrate(items) {
  // 我们以为: 这个 forEach 会一条条等 updateRecord 完成
  items.forEach(async (item) => {
    await updateRecord(item);   // 异步更新数据库
  });
  // 我们以为: 走到这里时, 上面 5000 条都更新完了
  console.log(`全部处理完成, 共 ${items.length} 条`);   // ← 它撒谎了
}

这段代码的"剧本",在我们脑子里是这样演的:forEach 遍历 5000 条,每条都 await updateRecord 等它更新完,全部更新完后,打印"全部处理完成"。多顺理成章。可实际上演的,却是另一出戏:forEach 在遍历时,对每一条都调用了那个 async 回调,而 async 回调一被调用,就立刻返回一个"还没完成的 Promise"(里面的 await updateRecord 才刚开始);但 forEach 对这个返回的 Promise 视而不见、直接丢弃,马上去处理下一条。于是它眨眼间就把 5000 个 updateRecord 全都"发射"了出去(它们都还在异步执行中),然后 forEach 自己结束了,代码继续往下走,那句"全部处理完成"就在这 5000 个任务大多还没落地时,被打印了出来。

那为什么数据库还能更新成功几十条呢?因为脚本打印完日志后,主流程可能很快就结束、进程退出了;在进程被杀死之前,那些"已经发射出去"的异步更新中,有少数几十个恰好抢在进程退出前完成了,所以落了几十条数据;剩下几千个还没来得及完成的,随着进程退出,全都灰飞烟灭了。这就是"日志说 5000、实际只有几十、每次还不一样"的全部真相——一场因为 forEach 不等待异步回调,而引发的"假完成"惨案。

第一件事:看懂 async 回调返回的是 Promise

要理解这个坑,先得建立一个关键认知:任何 async 函数,无论你在里面写没写 await、return 没 return 东西,它被调用后,立刻返回的都是一个 Promise 对象——而不是它内部最终算出的那个结果。这个 Promise 代表"一个将来会完成的异步操作";要拿到它内部真正的结果、或者要"等它完成",你必须 await 这个 Promise,或者用 .then() 挂回调。

async function task() {
  await delay(1000);
  return "done";
}

const r = task();        // r 不是 "done"! r 是一个 Promise 对象
console.log(r);          // Promise { <pending> }  —— 还没完成呢

const real = await task(); // 这样才拿到 "done"
console.log(real);         // "done"

回到 forEach 的坑:forEach(async item => ...) 里那个 async 回调,每次被调用都返回一个 Promise。问题是,forEach 这个方法的设计,是为同步回调准备的——它压根不看回调的返回值,拿到回调返回的 Promise 后直接扔掉,继续下一次迭代。所以这些 Promise 成了没人 await、没人 .then 的"野 Promise",在后台自生自灭。forEach 不是不能用异步回调,而是它对回调返回的 Promise 完全无感——它不会等,这才是坑的核心。

第二件事:正解——串行用 for...of,并发用 Promise.all

修法取决于你到底想要"串行"还是"并发"。先说串行(一条处理完再处理下一条,适合有顺序依赖、或想限制压力的场景):用最朴素的 for...of 循环,它配合 await 是真的会等。

// 串行: for...of + await 会一条条老老实实地等
async function migrate(items) {
  for (const item of items) {
    await updateRecord(item);   // 这个 await 真的会等它完成再进下一轮
  }
  console.log(`全部处理完成, 共 ${items.length} 条`);  // 现在它说的是真话
}

如果这些任务互相独立、你想并发执行以求更快(同时发起、一起等它们全部完成),正确做法是用 map 把每条映射成一个 Promise,再用 Promise.all 一次性等待全部:

// 并发: map 出一组 Promise, Promise.all 等它们全部完成
async function migrate(items) {
  await Promise.all(
    items.map(item => updateRecord(item))   // 同时发起所有更新
  );
  console.log(`全部处理完成, 共 ${items.length} 条`);  // 全部 resolve 后才打印
}

这两种写法的差别值得记牢:for...of + await 是串行,一个接一个,总耗时是所有任务之和,但对下游压力小、顺序可控;Promise.all(map(...)) 是并发,一起发起一起等,总耗时约等于最慢的那个,快得多,但会瞬间对下游(数据库、API)施加全部并发压力。怎么选,取决于任务是否有顺序依赖、以及下游扛不扛得住并发。而当数据量很大、又想并发但要控制并发度时(比如 5000 条但最多同时 10 个),还可以用分批(chunk)+ Promise.all,或者 p-limit 这类并发限制库——这是更精细的折中。但无论哪种,核心都是:用一个真正会"等待 Promise"的结构(for...of 或 Promise.all)去替换那个"假装在等"的 forEach。

我把这几种数组迭代方法对"异步等待"的支持情况画成一张图,这是这次踩坑后我最想让所有人记住的东西:

这张图的核心结论很简单粗暴:只要你需要"等异步操作完成",就别用 forEach——它是这几个数组方法里唯一一个会默默吞掉 Promise、永不等待的。 map 至少会把 Promise 收集起来还给你(让你能 Promise.all),而 forEach 连这个机会都不给你。理解了这点,你就再也不会写出那个"撒谎的批处理"了。

第三件事:同一个坑的变体——丢失的 await

顺着这次事故,我把代码库里所有异步相关的写法都扫了一遍,发现这个坑还有好几个"变体",根子都是一样的:一个该被 await 的 Promise,没被 await,于是程序没等它就往下跑了。最常见的是干脆忘了写 await:

async function handler() {
  // 忘了 await! saveToDb 返回的 Promise 没人等
  saveToDb(data);              // 火了, 但没等它
  return { ok: true };         // 可能在数据还没存进去时就返回了
  // 更糟: 如果 saveToDb 失败了, 这个异常你也根本接不住(见下一节)
}

// 正解: 该等的就 await
async function handler() {
  await saveToDb(data);        // 等它真的存好
  return { ok: true };
}

"丢失的 await"是 JS 异步里最高频的 bug 之一,危害有两层:一是时序错乱——你以为某个操作完成了才往下走,实际它还在后台跑,导致后续逻辑拿到的是旧状态、半成品(就像我们这次);二是异常逃逸——一个没被 await(也没 .catch)的 Promise,万一内部抛了错,这个错误会变成"未处理的 Promise 拒绝(unhandled rejection)",你的 try-catch 根本接不住它,它会在你意想不到的地方冒出来、甚至直接搞崩 Node 进程。所以一条铁律是:每当你调用一个返回 Promise 的函数,都要明确地决定——要么 await 它,要么用 .then/.catch 处理它,要么(确实是即发即忘时)显式注释说明"故意不等"。绝不要让一个 Promise 没人管。好在现在的 ESLint 有 no-floating-promises 这类规则,能自动揪出这种"没人管的 Promise",强烈建议开启。

第四件事:Promise.all 会"一个失败,全军覆没"

把 forEach 改成 Promise.all 之后,我们又踩了它的一个脾气:Promise.all 是"一票否决"的——只要其中任意一个 Promise 失败(reject),整个 Promise.all 就立刻 reject,你只能拿到那第一个错误,而其余那些其实成功了的、或者也失败了的结果,你统统拿不到。对"5000 条里允许个别失败、但想知道到底哪些成功哪些失败"的批处理来说,这个行为往往不是你要的——一条出错,你就丢了全部信息。

// Promise.all: 一个失败, 整体就 reject, 拿不到其它结果
try {
  await Promise.all(items.map(updateRecord));
} catch (e) {
  // 只知道"有一个失败了"和它的错误, 不知道其余 4999 条情况如何
}

// Promise.allSettled: 等全部结束, 逐个告诉你成败 (要分别处理时用它)
const results = await Promise.allSettled(items.map(updateRecord));
const ok = results.filter(r => r.status === "fulfilled");
const failed = results.filter(r => r.status === "rejected");
console.log(`成功 ${ok.length} 条, 失败 ${failed.length} 条`);
// failed 里每个都带着各自的 reason, 可以记录/重试

所以这里要分清两个孪生方法的适用场景:Promise.all 适合"全部成功才算成功、一个失败就该整体放弃"的场景(比如并行加载一个页面必需的几份数据,缺一不可);Promise.allSettled 适合"允许部分失败、且想分别知道每个的成败"的场景(比如批量处理、群发,失败的单独记录或重试)。我们这次的批处理,显然该用 allSettled——它会老老实实等所有任务都结束(无论成败),然后给你一份逐条的成败清单,让你能精确统计、能把失败的挑出来重试,而不是一条失败就两眼一抹黑。把几个 Promise 组合方法的脾气列个表对比一下:

第五件事:理解事件循环——异步的"心脏"

这次事故逼着我把 JavaScript 异步的"心脏"——事件循环(Event Loop)——彻底搞明白了。因为只有理解了它,你才能真正预测"几段异步代码的执行顺序"。JS 是单线程的,它靠事件循环来调度异步任务,而任务分两类:宏任务(macrotask)(如 setTimeout、IO、整体脚本)和微任务(microtask)(如 Promise 的 .then/await 之后的代码)。关键规则是:每执行完一个宏任务,会把当前积累的所有微任务清空,然后才取下一个宏任务。

console.log("1 同步");
setTimeout(() => console.log("2 宏任务 setTimeout"), 0);
Promise.resolve().then(() => console.log("3 微任务 then"));
console.log("4 同步");

// 输出顺序: 1, 4, 3, 2  (而不是 1,2,3,4!)
// 解释: 先跑完所有同步代码(1,4);
//      再清空微任务(3);  ← 微任务优先于宏任务
//      最后才执行宏任务(2)

这个 1, 4, 3, 2 的顺序,坑过无数人。它揭示了两条核心规律:一是同步代码永远先全部跑完,异步回调(无论微任务宏任务)都得等同步代码执行完才有机会运行;二是微任务的优先级高于宏任务——一批微任务会在下一个宏任务之前被"插队"清空。而 await 后面的代码,本质上就是被包装成了微任务。理解了这套调度规则,很多"为什么这段代码的打印顺序和我想的不一样""为什么 setTimeout(fn,0) 不是立刻执行"的困惑,就都迎刃而解了。我把这套调度画成一张图:

这张图最该记住的,是那个"每个宏任务之后,必清空全部微任务,再取下一个宏任务"的循环节奏。它解释了为什么 Promise 的回调总是比 setTimeout "更早"执行(微任务优先),也解释了为什么一段拼命产生微任务的代码可能会"饿死"宏任务。对大多数业务开发,你不需要时时刻刻惦记这张图;但当你遇到异步执行顺序的诡异问题时,它就是你手里那把能解开一切的钥匙。异步编程的种种"反直觉",归根到底都能在这张事件循环图里找到解释——它才是 JavaScript 异步世界真正的运行法则。

把数组方法对异步的态度列成一张表

这次踩坑后,我把常用的数组遍历方式对"异步等待"的支持,汇成一张速查表,贴在团队 wiki 上。下次写"遍历数组做异步操作"时,先瞄一眼这张表,别再凭直觉了:

这张表的中心思想就一句:当你需要"等异步操作完成"时,你的选择是 for...of(串行)或 Promise.all/allSettled(并发),而 forEach(async) 是唯一一个会骗你的——它名义上接受 async 回调,实际上对回调的 Promise 不管不顾。把这张表的结论刻进肌肉记忆,这一整类"异步没等就往下跑"的 bug 就基本绝迹了。

我立下的几条 JS 异步铁律

这次"撒谎的批处理"事故后,团队的前端/Node 规范里多了这么几条:

1. 需要等待就别用 forEach:遍历做异步且要等完成,用 for...of(串行)或 Promise.all/allSettled(并发),forEach 仅限确认"即发即忘"的场景。
2. 每个 Promise 都要有归宿:调用返回 Promise 的函数,必须 await、或 .then/.catch、或显式注释"故意不等";开启 ESLint 的 no-floating-promises。
3. 分清 all 与 allSettled:全成才算成用 all;允许部分失败、要逐条结果用 allSettled,别让一条失败丢掉全部信息。
4. 大批量要限并发:几千上万条别无脑 Promise.all 全发出去打垮下游,用分批或 p-limit 控制并发度。
5. 异步异常要兜住:async 函数里用 try-catch,顶层加 unhandledRejection 监听,别让异步异常静默逃逸。
6. 脚本退出前等异步完成:Node 脚本结尾确保所有异步都 await 完再让进程自然结束,避免"任务还没干完进程就退了"。
7. 顺序存疑就回到事件循环:遇到执行顺序诡异的 bug,用"同步先行、微任务优先于宏任务"这把钥匙去推演。

这几条里,第一、二条是直接堵死这次事故的,而第二条"每个 Promise 都要有归宿"我想格外强调——它几乎是 JS 异步安全的总纲。我们这次的 bug、丢失的 await、未处理的 rejection,根子都是"产生了一个 Promise,却没人负责它的结局"。把"绝不放任一个 Promise 自生自灭"当成铁律,再用 ESLint 强制兜底,你就堵死了 JS 异步里一大半的坑。

写在最后:异步不是"语法糖",是"思维方式"

这次被一个 forEach 坑到怀疑人生的经历,最大的收获,是彻底纠正了我对 async/await 的一个根本误解。在那之前,我把 async/await 当成了一种"让异步代码长得像同步代码"的语法糖,潜意识里以为:只要我加上 async、await,代码就会"像同步那样,从上到下、一行等一行地老实执行"。可这次事故狠狠地告诉我:async/await 确实让异步代码"看起来"像同步,但它骨子里依然是异步的——它没有、也不可能改变 JavaScript 单线程、事件循环、Promise 调度这套底层运行机制。它美化了语法,却没有、也不该让你忘记异步的本质。而我那次,恰恰就是被它"像同步"的外表骗了,以为 forEach 里的 await 会像同步循环那样老实等待——可 forEach 这个为同步而生的方法,根本不吃 await 这一套。

想通这一层,我对异步编程的心态成熟了:我不再把 async/await 当成"可以不用懂异步原理的免死金牌",而是把它看作一套需要配合底层机制(Promise、事件循环)来理解的工具。写每一段异步代码时,我会多问自己几个问题:这个返回 Promise 的调用,谁来等它?这些任务该串行还是并发?如果其中一个失败了会怎样?进程会不会在它们完成前就退出?——这些问题,语法糖不会替你回答,只有对异步本质的理解才能。语法糖降低了书写的门槛,却没有降低理解的门槛;而真正决定你能不能写出可靠异步代码的,从来是后者。

所以,如果你也在写 JavaScript / Node,我想把这次踩坑最想说的话送给你:别被 async/await "像同步"的外表迷惑,请在它优雅的语法之下,扎扎实实地理解 Promise 是什么、事件循环怎么转、哪些方法会等待 Promise 而哪些不会。当你真正理解了异步的运行机制,你写下的每一个 await、每一次 Promise.all,才不再是"照着模板抄"的猜测,而是"我清楚它会怎么执行"的笃定。那次安静地"撒谎"了一回的批处理脚本,最终教给我的,正是这份对异步本质的敬畏——别让一个 Promise 没人管,别让一句 await 名不副实,别让"看起来对"代替"真的懂"。愿你我都不必再经历那种"日志说完成了、数据却没动"的崩溃,把每一个异步任务,都稳稳地等到它真正落地。

一个延伸:别让"静默成功"骗了你

这次事故还留给我一个超越 JavaScript、适用于一切系统的教训:最危险的 bug,不是那些大吵大闹地报错崩溃的,而是那些"静默成功"的——程序一脸平静地告诉你"我完成了",实际却悄悄漏掉了大半工作。报错的 bug 至少诚实,它把问题摆在你面前;而"静默成功"的 bug 是会撒谎的,它用一句"全部处理完成"和一个为 0 的退出码,把你哄得心满意足,等你某天发现数据对不上,早已过去很久、追查无门。我们这次要不是恰好去核对了数据库条数,这个"撒谎的脚本"可能还会继续骗我们很久。

所以,从这次之后,我对程序"声称的成功"多了一份警惕,养成了一个习惯:对关键操作,不只看它"有没有报错",更要主动去核验它"真的产生了预期的结果"。批处理跑完,不光看日志说处理了多少条,更要回查数据库实际更新了多少条,两个数字对得上才算数。这种"用结果反向验证过程"的较真,看似多此一举,却是揪出"静默成功"类 bug 的唯一办法。程序说的"我完成了"只是它的一面之词;真正的完成,要靠你去核对结果来确认。这份不轻信、要验证的工程素养,大概是那个"撒谎的批处理"送给我的、比任何异步知识都更宝贵的东西。

说到底,异步编程考验的不只是你对语法的熟练,更是你对"事情有没有真的做完"这件事的较真程度——把这份较真带在身上,无论用什么语言、什么框架,你都能少踩很多看不见的坑。

—— 别看了 · 2026