踩坑日记：如何修复“System limit for number of file watchers reached”错误

今天遇到了一个常见的系统错误，当启动 Next.js 项目时，终端打印出了一个报错

“Watchpack Error (watcher): Error: ENOSPC: System limit for number of file watchers reached, watch …”

这个错误经常在开发过程中遇到，“System limit for number of file watchers reached”意思是“达到文件观察者数量的系统限制”。错误产生的原因是负责监控 Linux 文件系统的 inotify 程序达到了系统默认的限制上限。

Inotify 是什么？

inotify 是 Linux 内核 2.6.13 (June 18, 2005) 版本新增的一个子系统（API），它提供了一种监控文件系统（基于 inode 的）事件的机制，可以监控文件系统的变化如文件修改、新增、删除等，并可以将相应的事件通知给应用程序。几乎所有的主流 Linux 发行版都支持 Inotify 机制。如何知道你的 Linux 内核是否支持 Inotify 机制呢？很简单，执行下面这条命令：

grep INOTIFY_USER /boot/config-$(uname -r)
CONFIG_INOTIFY_USER=y

如果输出 CONFIG_INOTIFY_USER=y，代表当前系统支持 Inotify 机制。

解决方案

介绍2种修复“System limit for number of file watchers reached”错误的方法（以 Ubuntu 22.04 为例）。

查看 Inotify 在内核中的默认配置。

sysctl fs.inotify
fs.inotify.max_queued_events = 16384 # inotify 管理的队列的最大长度
fs.inotify.max_user_instances = 128 # 每个用户所能创建的 Inotify 实例的上限
fs.inotify.max_user_watches = 65536 # 每个 Inotify 实例最多能关联几个监控 (watch)

或者

cat /proc/sys/fs/inotify/max_queued_events
16384
cat /proc/sys/fs/inotify/max_user_instances
128
cat /proc/sys/fs/inotify/max_user_watches
65536

方法一：增加 inotify watchers 的上限数量（临时）

可以临时修改 inotify 中 watcher 的上先数量，提高数量上限，方法如下：

sudo sysctl fs.inotify.max_user_watches=524288
sudo sysctl -p
cat /proc/sys/fs/inotify/max_user_watches
524288

方法二：增加 inotify watchers 的上限数量（永久）

但上述方法只是临时修改了 inotify 的 watcher 上限数量，但重启后就会恢复 inotify 的默认设置。可以用以下方法永久修改：

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
cat /proc/sys/fs/inotify/max_user_watches
524288

方法三：减少 inotify 监控的文件数量

关闭或者减少 inotify 监控的文件。以前端开发为例，如果报错来自 VSCode ，可以关闭再重新打开 VSCode 。

如果是 Webpack 引起的错误，可以通过在 webpack.config.js 文件中设置 watchOptions 属性，尝试排除node_modules 文件夹。

module.exports = {
  //...
  watchOptions: {
    ignored: /node_modules/,
  },
};

或者重新安装 node_modules

rm -rf node_modules # 删除 node_modules
npm cache clean --force # 强制清理 npm 缓存
pnpm install # 使用 pnpm 重新安装 node_modules