forEach async 為什麼沒等完？用 for...of 或 Promise.all 接住工作

2026-10-22

前端

JavaScript

/

前端開發

/

疑難排解

/

最佳實踐

把儲存動作放進 items.forEach(async item => { await save(item); })，下一行卻已顯示「完成」，甚至先跳頁。原因是 forEach 不會等待 callback 回傳的 Promise，外層的 await 也不會幫它收集工作。需要依序完成，用 for...of；工作彼此獨立、可以同時啟動，再用 map 建立 Promise 陣列交給 Promise.all。

先決定順序與失敗策略，再選語法。若第二筆失敗時第三筆不能開始，並行啟動就不符合需求，事後加 catch 也無法撤回已經送出的操作。

用一個閘門證明 forEach 已經回傳#

MDN 的 forEach 說明明確指出它不等 Promise，回傳值為 undefined。ECMAScript 演算法也沒有收集 callback 結果的步驟。

以下範例把工作停在可手動放行的 Promise，避免用「延遲幾秒」猜測順序。將每個 JavaScript 區塊分別存成 .mjs，用 node 檔名.mjs 執行；正常結果是沒有 assertion 錯誤。

1
import assert from 'node:assert/strict';
2

3
function deferred() {
4
  let resolve;
5
  const promise = new Promise((ok) => { resolve = ok; });
6
  return { promise, resolve };
7
}
8

9
const gate = deferred();
10
const finished = deferred();
11
const completed = [];
12
const returned = await [1, 2].forEach(async (id) => {
13
  await gate.promise;
14
  completed.push(id);
15
  if (completed.length === 2) finished.resolve();
16
});
17

18
assert.equal(returned, undefined);
19
assert.deepEqual(completed, []); // 外層 await 已結束，工作仍被擋住
20

21
gate.resolve();
22
await finished.promise; // 測試另外建立完成訊號，forEach 本身沒有提供
23
assert.deepEqual(completed, [1, 2]);

這個重現刻意只使用成功工作。若 async callback 內拋錯，會變成該 callback 的 Promise rejection；包住 await items.forEach(...) 的外層 try/catch 接不到這個被忽略的 Promise。改成能回傳整批完成狀態的流程，才能讓呼叫端等待並處理失敗。

後一筆依賴前一筆，就用 for…of#

例如逐筆套用有順序的更新，或第一個錯誤就應停止後續操作，可直接在迴圈內等待。下面的 helper 接受一般、無空洞的陣列；save 必須回傳代表工作完成的 Promise，或在同步完成後回傳值。

1
import assert from 'node:assert/strict';
2

3
async function saveInOrder(items, save) {
4
  const results = [];
5
  for (const item of items) {
6
    results.push(await save(item));
7
  }
8
  return results;
9
}
10

11
const calls = [];
12
const failure = new Error('第二筆失敗');
13
await assert.rejects(
14
  saveInOrder([1, 2, 3], async (id) => {
15
    calls.push(id);
16
    if (id === 2) throw failure;
17
    return `saved:${id}`;
18
  }),
19
  (error) => error === failure,
20
);
21
assert.deepEqual(calls, [1, 2]); // 第三筆根本沒有啟動
22
assert.deepEqual(
23
  await saveInOrder([1, 2], async (id) => `saved:${id}`),
24
  ['saved:1', 'saved:2'],
25
);
26
assert.deepEqual(await saveInOrder([], async (id) => id), []);

這裡的「停止」只表示不啟動下一筆，不會撤銷已成功的第一筆。若整批必須全部成功或全部撤回，要在資料庫交易或業務補償流程處理。save 若只是啟動背景工作便立刻回傳，外面的 await 仍不知道背景何時結束。

可以並行才改成 map，確認結果與完成順序不同#

map 保留 callback 回傳值，因此能把 Promise 交給聚合器。範例使用 async wrapper，即使 save 同步拋錯，也會成為可等待的 rejection。

1
import assert from 'node:assert/strict';
2

3
async function saveTogether(items, save) {
4
  return Promise.all(items.map(async (item) => save(item)));
5
}
6

7
function deferred() {
8
  let resolve;
9
  const promise = new Promise((ok) => { resolve = ok; });
10
  return { promise, resolve };
11
}
12

13
const gates = new Map([[1, deferred()], [2, deferred()]]);
14
const completed = [];
15
const batch = saveTogether([1, 2], async (id) => {
16
  await gates.get(id).promise;
17
  completed.push(id);
18
  return `saved:${id}`;
19
});
20

21
gates.get(2).resolve();
22
await Promise.resolve(); // 讓第二筆先通過自己的 await
23
assert.deepEqual(completed, [2]);
24
gates.get(1).resolve();
25
assert.deepEqual(await batch, ['saved:1', 'saved:2']);
26
assert.deepEqual(completed, [2, 1]);
27

28
const failure = new Error('同步失敗');
29
await assert.rejects(
30
  saveTogether([1], () => { throw failure; }),
31
  (error) => error === failure,
32
);
33
assert.deepEqual(await saveTogether([], async (id) => id), []);