ESLint 项目中的 EMFILE 错误分析与解决方案

在大型 TypeScript 项目中，当使用 ESLint 进行代码检查时，开发者可能会遇到一个棘手的问题：EMFILE 错误（"too many open files"）。这个问题通常出现在项目包含大量文件（如 20,000 个以上的 ts/tsx 文件）时，特别是在使用 Flat Config 配置和 @typescript-eslint/parser 解析器的情况下。

问题现象

当 ESLint 尝试同时处理大量文件时，系统会达到文件描述符的限制，导致出现 EMFILE 错误。错误信息通常如下：

Error: EMFILE: too many open files, open 'path/to/file.ts'

在某些情况下，还可能出现"Maximum call stack size exceeded"的调用栈溢出错误。这些问题在 ESLint v8.57.0 及以下版本中不会出现，但在 v9.x 版本中变得明显。

问题根源

经过深入分析，这个问题主要由以下几个因素共同导致：

1. 文件并发读取：ESLint v9 采用了更积极的文件读取策略，导致同时打开的文件数量激增
2. TypeScript 插件开销：@typescript-eslint 插件在初始化时会进行额外的文件系统操作
3. 重试机制限制：内置的 retry 包在处理大量文件时存在调用栈溢出的风险
4. 系统资源限制：操作系统对单个进程可打开的文件数量有默认限制

解决方案演进

ESLint 团队针对这个问题提出了几种解决方案：

1. 增加重试超时时间：通过修改 retry 包的超时参数，给系统更多时间释放文件描述符

   • 测试表明，30-60 分钟的超时可以解决大部分情况
   • 但这不是根本解决方案，且在某些环境下仍然会失败

2. 限制并发读取：引入并发控制机制，限制同时进行的文件读取操作数量

   • 这种方法更高效，能减少内存消耗
   • 即使将并发限制为 1，在某些系统上仍可能出现 EMFILE 错误

3. 智能重试机制：结合并发控制和针对 EMFILE 错误的特殊处理

   • 对 EMFILE 错误进行无限重试
   • 对其他错误保持原有处理逻辑

最佳实践建议

对于遇到此问题的开发者，可以采取以下临时解决方案：

1. 升级到最新 ESLint 版本：v9.14.0 及以上版本已包含相关修复
2. 调整系统限制：临时增加系统的文件描述符限制
   • 在 Linux/Mac 上：ulimit -n 4096
3. 分批处理：将大型项目分成多个部分分别检查
4. 使用修复分支：在官方正式修复前，可以使用特定分支版本

技术启示

这个问题揭示了在现代前端工具链中处理大型项目时面临的挑战：

1. 工具设计需要考虑规模扩展性：随着项目规模增长，工具的行为可能发生质变
2. 系统资源管理：工具需要智能地管理系统资源，避免耗尽限制
3. 错误恢复策略：对于可恢复错误（如临时资源不足）应有完善的恢复机制

ESLint 团队对此问题的处理展示了开源社区如何协作解决复杂技术问题，从问题重现、根源分析到多种解决方案的提出和验证，最终为用户提供稳定可靠的工具体验。