核心用法
本 Skill 是针对 Node.js 运行时常见陷阱的系统性避坑指南，聚焦 7 大高危领域：
1. 事件循环阻塞
- 同步 I/O（如
fs.readFileSync）会阻塞整个线程，必须用fs.promises.readFile或流式 API - CPU 密集型任务应 offload 到 Worker Threads 或子进程
- 长循环需分片执行，通过
setImmediate释放 I/O
2. 异步错误处理
- Node 15+ 未处理的 Promise 拒绝会直接导致进程崩溃
- 必须配合
.catch()或 try/await 使用，建议配置全局unhandledRejection处理器优雅退出 Promise.all快速失败特性常被忽视，需结果全量时用Promise.allSettled
3. ESM 迁移陷阱
__dirname不存在于 ESM，需通过import.meta.url转换- CommonJS 无法 require() ESM 模块，必须用动态
import() exports重赋值会破坏模块导出
4. 内存管理
- 事件监听器累积、闭包引用大对象、无界全局缓存是三大泄漏源头
- 建议采用 LRU 缓存并设置
--max-old-space-size仅为临时手段
5. 流式处理
- 手动
write()需处理背压（返回 false 时等待 drain），优先使用pipeline()替代.pipe()自动处理错误与资源释放
显著优点
- 覆盖 Node.js 生产环境 90% 以上的崩溃/性能问题根源
- 与官方文档行为一致，无偏方或过时技巧
- 可直接映射到代码审查清单
潜在局限
- 未涉及 Node.js 特定版本差异（如 18+ 的 native fetch 行为）
- 对集群模式、PM2 等部署层问题无覆盖
- 无性能基准数据，"阻塞"概念依赖开发者主观判断
适合人群
- 中级 Node.js 开发者（已能写业务代码，需提升健壮性）
- 从浏览器端迁移至 Node 的全栈工程师
- 负责代码审查的 Tech Lead
常规风险
- 全局
unhandledRejection处理器若设计不当可能掩盖错误 - Worker Threads 引入共享内存需额外 Atomics 知识
- ESM 与 CommonJS 混用项目易出现隐式加载行为差异