解决 umijs/mako 开发服务器文件监控过多导致无法自动刷新的问题

问题现象

在使用 umijs/mako 构建工具进行项目开发时，部分开发者遇到了开发服务器无法自动刷新的问题。具体表现为：

1. 控制台报错 Error watching files: Too many open files (os error 24)
2. 修改文件后无法触发热更新
3. 即使手动刷新浏览器，获取到的仍然是旧内容
4. 只有重启开发服务器才能获取到最新编译结果

这个问题在 monorepo 项目和大型项目（如 antd）中尤为常见，特别是在 macOS 系统上。

问题根源分析

经过技术分析，该问题的根本原因在于文件监控机制：

1. 文件描述符限制：操作系统对单个进程能打开的文件描述符数量有限制（通常为 2560 左右）
2. 监控机制选择：mako 默认使用了 macos_kqueue 作为文件监控机制
3. 监控方式差异：
   • kqueue 机制需要为每个监控的文件/目录单独打开文件描述符
   • 大型项目中监控的文件数量很容易超过系统限制
4. 项目规模影响：monorepo 项目或依赖较多的大型项目（如 antd）更容易触发此问题

解决方案

针对这一问题，社区提出了几种解决方案：

1. 调整文件监控机制

将默认的 macos_kqueue 改为 macos_fsevent：

• fsevent 是 macOS 专有的文件系统事件通知机制
• 可以监控整个目录树而无需为每个文件单独打开描述符
• 显著减少文件描述符的占用

2. 系统级调整

临时提高系统的文件描述符限制：

ulimit -n 65536

但这只是临时解决方案，重启终端后会失效。

3. 忽略不必要的监控路径

通过配置 watch.ignorePaths 忽略不需要监控的目录，如：

• node_modules
• 构建输出目录
• 文档目录等

最佳实践建议

1. 大型项目推荐：对于 monorepo 或依赖较多的大型项目，建议优先使用 fsevent 机制
2. 开发环境配置：可以在项目启动脚本中加入 ulimit 调整命令
3. 监控优化：合理配置忽略路径，减少不必要的文件监控
4. 持续关注：关注 mako 项目的更新，该问题已在 #1550 中修复

技术原理深入

理解不同文件监控机制的工作原理有助于更好地解决此类问题：

1. kqueue：

   • BSD 系统的事件通知接口
   • 通用性强，可用于多种类型的事件监控
   • 每个监控对象需要独立的文件描述符
   • 适合监控少量文件

2. FSEvents：

   • macOS 专属的文件系统事件API
   • 基于目录树监控，效率高
   • 单个监控器可监控整个目录及其子目录
   • 特别适合大型项目

3. inotify：

   • Linux 系统的文件系统监控机制
   • 也支持目录树监控
   • 在 Linux 环境下是更好的选择

总结

文件监控是现代化前端构建工具的重要功能，但在处理大型项目时需要特别注意系统资源的合理利用。通过选择合适的监控机制和优化监控策略，可以有效解决 umijs/mako 开发服务器自动刷新失效的问题，提升开发体验。