Iterator.prototype.flatMap仅支持同步迭代器，因其实现于Symbol.iterator协议，无法识别Symbol.asyncIterator协议的异步数据源，故不能处理Promise或AsyncIterator。
Iterator.prototype.flatMap 本身不支持异步操作，它只处理同步可迭代对象（如数组、Set、Generator 函数返回的同步迭代器），且其回调函数必须返回一个同步可迭代值。因此，不能直接用它扁平化“异步数据链路”（例如 Promise、AsyncIterator）。
为什么 flatMap 无法处理异步数据？
因为 Iterator.prototype.flatMap 是 ES2025 新增的 同步迭代器辅助方法，定义在 Iterator 接口上，仅作用于实现了 @@iterator 的对象（即 [Symbol.iterator]() 返回同步迭代器）。而异步数据源（如 for await...of 可遍历的对象）实现的是 [Symbol.asyncIterator]()，属于 AsyncIterator 协议 —— 这是完全不同的协议，flatMap 不识别也不兼容。
- 传入 AsyncIterator（如
async function*()的结果）会报错：TypeError: xxx is not iterable - 回调中返回
Promise或async function，flatMap 会把它当作普通值（比如包装成[Promise]），不会等待，更不会展平其 resolve 结果 - 目前（2026年5月）标准中尚无 AsyncIterator.prototype.flatMap，TC39 尚未提案或进入 Stage 3
替代方案：用 for await + 手动展平或组合工具
要真正扁平化嵌套的异步数据链路（例如：从多个 API 分页请求中拉取多层子列表），需切换到异步语境，常用方式有：
-
逐层 await + 展开：适合层数固定、逻辑清晰的场景
const results = [];<br>for await (const page of fetchPages()) {<br> for await (const item of fetchItems(page.id)) {<br> results.push(item);<br> }<br>} -
用 Promise.all + flatMap 模拟：先收集所有异步任务，再并发执行并展平
const pages = await getAllPages();<br>const itemArrays = await Promise.all(<br> pages.map(page => fetchItems(page.id))<br>);<br>const allItems = itemArrays.flat();
-
封装为 AsyncIterator 工具函数（推荐）：
自定义asyncFlatMap辅助函数，内部用for await和yield*实现惰性展平：async function* asyncFlatMap(iter, mapper) {<br> for await (const item of iter) {<br> const subIter = await mapper(item);<br> if (subIter[Symbol.asyncIterator]) {<br> yield* subIter;<br> } else if (Array.isArray(subIter)) {<br> for (const x of subIter) yield x;<br> }<br> }<br>}
使用：for await (const item of asyncFlatMap(apiPages(), page => fetchItemsAsync(page.id))) { ... }
注意边界与常见坑
避免把同步 flatMap 错误用于异步上下文：
- ❌
someAsyncIterator.flatMap(x => fetch(x))→ 类型错误，someAsyncIterator不是 Iterable - ❌
Array.from(someAsyncIterator).flatMap(...)→ 先试图同步展开异步迭代器，失败 - ✅ 正确思路：区分协议 —— 同步用
Iterator.prototype.flatMap，异步用for await链或自定义异步工具 - ⚠️ 异步扁平化天然涉及并发控制（如限流）、错误传播（某次 fetch 失败是否中断整体）、内存压力（避免一次性加载全部数据），这些是同步 flatMap 完全不考虑的维度
本质上，异步数据链路的“扁平化”不是结构转换问题，而是控制流编排问题。flatMmap 解决的是“如何把树形结构摊成线性序列”，而异步链路需要解决的是“何时发起请求、如何合并响应、怎样容错重试”。两者目标不同，工具自然不同。
