Async避坑指南：10个常见陷阱——回调栈溢出、多次callback与同步迭代器

Async避坑指南：10个常见陷阱——回调栈溢出、多次callback与同步迭代器

【免费下载链接】asyncAsync utilities for node and the browser项目地址: https://gitcode.com/gh_mirrors/as/async

Async 是 Node.js 生态中最流行的异步任务处理库，为 Node 和浏览器提供了each、map、auto、retry等强大的异步迭代与流程控制工具。这篇Async 避坑指南整理了新手使用 Async 库时最容易踩中的 10 个陷阱——回调栈溢出、多次调用 callback、同步迭代器误用等，并给出对应的排查思路和规避方案，帮你在使用异步工具函数时少走弯路、快速上手。

Async 避坑清单：10 个陷阱速览

先给出一张速查表，方便按图索骥：

一、回调栈溢出：同步回调引发的“Zalgo”

为什么同步回调会导致栈溢出

Async 的核心设计前提是：iteratee（迭代函数）必须在异步的后续 tick 中调用 callback。如果你写了一个“缓存命中就同步回调”的函数：

function sometimesAsync(arg, callback) { if (cache[arg]) return callback(null, cache[arg]); // 同步！ doSomeIO(arg, callback); // 异步 } async.mapSeries(args, sometimesAsync, done);

连续多次缓存命中时，同步调用会一层层压入调用栈，最终抛出RangeError: Maximum call stack size exceeded。这种现象在异步圈有个著名的名字叫Zalgo（异步混乱）。

最快修复方法：ensureAsync 包裹

Async 官方提供了 ensureAsync：它检测函数是否在同步路径上调用了回调，若是就自动推迟到下一 tick（内部通过 setImmediate 实现，参考 nextTick.js 的降级策略）：

async.mapSeries(args, async.ensureAsync(sometimesAsync), done);

💡 记忆点：只要函数“可能同步”，就值得包一层ensureAsync。原生async函数不受影响——它们天然在后续 tick 完成，wrapAsync.js 中的isAsync判断会直接放行。

二、多次调用 callback：“Callback was already called”

最常见的错误：if/else 没写全

async.each(list, (item, cb) => { if (item.fail) cb(new Error('bad item')); doWork(item).then(() => cb()); // cb 被调了两次！ }, done);

Async 内部用 onlyOnce 保护每个任务的回调：第二次调用会直接抛出Error: Callback was already called.（例如 eachOf.js 中每个iteratorCallback都被onlyOnce包裹）。而最外层的 done 回调则通过 once 静默丢弃多余调用——这意味着第二次触发往往无声无息，比报错更危险。

规避建议

• 每个分支调用 callback 后紧跟return；
• try/catch捕获后return callback(e)，参考 README.md 中的官方示例写法；
• Promise 链末尾统一.then(() => cb()).catch(cb)，不要两边都写。

三、忘记调用 callback：任务永远“失联”

回调风格没有 try/finally 兜底。任何提前 return 或抛异常的路径若漏调 callback，Async 就永远等不到该任务完成，整个流程静默挂起——没有报错、没有超时，只有“卡住了”。

排查建议：给外层套一个 timeout 或 retry 兜底，并养成“callback 与 return 成对出现”的代码审查习惯。

四、Promise 与 callback 混用：二选一原则

Async v3 全面支持 Promise：不传 callback 时，函数直接返回 Promise（由 awaitify.js 实现），内部通过 promiseCallback.js 桥接。

典型坑是“两边都要”：

// 错误示范：又 await 又传 callback，行为混乱 async.map(list, async item => { const r = await fetch(item); callback(); // ← 多余且危险 }, done);

✅ 正确姿势：iteratee 是 async 函数就return结果；是回调函数就只调 callback。一条任务路径只承诺一种完成方式。

五、同步迭代器误用：each 与 eachOf 分不清

参数顺序陷阱

• async.each(collection, (item, index, callback) => …)—— 面向数组；
• async.eachOf(collection, (item, key, callback) => …)—— 面向对象/映射，第二个参数是 key（见 eachOf.js 的文档说明）。

用each遍历对象时，key 和 value 会错位——这是新手最高频的坑之一。

同步迭代器与异步迭代器

Async 支持数组、对象、可迭代对象（Iterator）、异步可迭代对象（AsyncIterable）。内部通过 getIterator.js 取Symbol.iterator迭代器。注意两点：

• 同步迭代器（Symbol.iterator）在 v3 各版本中的支持程度不同，若传入的“迭代器”不产生预期元素，先确认它是同步还是异步迭代器；
• 异步生成器（Symbol.asyncIterator）需要 v3 较新版本支持，参考 wrapAsync.js 中isAsyncIterable的判定逻辑，以及 test/es2017/asyncGenerators.js 中的官方用例。

六、map 结果被丢弃：忘记把结果传给 callback

async.map收集的是你通过 callback 传递的值，而不是函数的return（回调风格下）。

async.map(urls, (url, cb) => { fetchJson(url, (err, data) => cb(err)); // ❌ 丢了 data }, done); async.map(urls, (url, cb) => { fetchJson(url, (err, data) => cb(err, data)); // ✅ }, (err, results) => { /* results 是 data 数组 */ });

如果是 async 函数风格，则return response.body即可（见 README.md 官方示例）。同理，reduce、sortBy、groupBy等收集类 API 都遵循此约定。

七、提前退出：用 callback(false) 优雅 break

很多任务“找到第一个满足条件的即可”。Async 约定：回调第一个参数传false表示中止（err === false时置canceled标志，见 eachOf.js）。

async.each(tasks, (task, cb) => { if (doneCondition) return cb(false); // 等价于 break // … }, (err) => { /* 正常退出时 err 为 null */ });

不要自己return或抛错来“假装”退出——那会被当作失败处理。

八、并发不受控：默认全速并行

async.map、async.each等并行 API 默认全部同时执行（内部 parallel.js 不加并发限制）。几百个 URL 一次性轰向接口，轻则限流，重则拖垮服务。

解法很简单——换用*Limit版本并给出并发数：

async.mapLimit(urls, 5, processUrl, done); // 最多 5 个并发 async.eachLimit(items, 3, process, done);

需要严格串行就用*Series版本。选择口诀：有限资源用 Limit，有依赖用 auto/waterfall，无所谓用 Series。

九、错误未处理：Unhandled Promise Rejection

回调风格下done的err参数、Promise 风格下的catch，都是必须处理的。Async 不会替你打印错误——被省略的 callback、未 await 的 Promise，最终都变成难排查的静默失败。

推荐规范：

• 回调：done中先if (err) return handle(err);；
• Promise：await async.map(…)包在try/catch里；
• 对网络类错误可叠加 retry / retryable 做自动重试与指数退避。

十、版本与 API 漂移：确认你在用 v3

v2 → v3 变化很大：v3 全面支持 Promise/async-await，且部分函数（如while/doWhile的废弃与doWhilst保留、cargoQueue新增等）行为不同。仓库内保留了 v2 与 v3 两套文档，可对照检查你的 API 用法：

• v3 文档入口：docs/v3/index.html
• v2 文档入口：docs/v2/index.html

不确定行为时，直接翻 test/ 下同名测试文件（如 test/map.js、test/retry.js），它们就是最权威的用法示例。

Async 避坑自检清单 ✅

完成开发前，逐条过一遍这份清单：

• 可能同步完成的函数已用ensureAsync包裹？
• 每个分支 callback 只调用一次，且有return保护？
• 所有异常路径（try/catch、Promisecatch）都会结束任务？
• 并行任务已用*Limit限制并发？
• err/catch均有处理逻辑？
• 对象遍历用的是eachOf而非each？

参考资料

• 项目说明与快速上手：README.md
• 工具函数源码目录：lib/（内部实现见 lib/internal/）
• 完整 API 文档：docs/v3/docs.html
• 测试用例（最佳实践参考）：test/

掌握以上 10 个陷阱的规避方法，Async 库的callback 栈溢出、多次 callback、同步迭代器等高频问题就基本与你说再见了。

【免费下载链接】asyncAsync utilities for node and the browser项目地址: https://gitcode.com/gh_mirrors/as/async