Heroku部署Laravel9启动Vite报ENOSPC文件监听器达系统上限

• Vite版本：v2.9.14
• 框架版本：Laravel v9.19.0
• 触发场景：Heroku平台部署Laravel 9项目，启动Vite开发服务时触发报错

Vite服务启动初始输出：

本地访问: http://localhost:3000/
网络访问: 使用 --host 参数暴露服务

服务启动就绪耗时309ms。

APP_URL: http://localhost
node:internal/errors:465 timing config:load:flatten 执行完成，耗时5ms
ErrorCaptureStackTrace(err);
^

核心报错：

Error: ENOSPC: System limit for number of file watchers reached, watch '/app/vendor/league/commonmark/src/Extension/CommonMark/Delimiter/Processor'

完整错误堆栈：

at FSWatcher. (node:internal/fs/watchers:244:19)
at Object.watch (node:fs:2264:34)
at createFsWatchInstance (/app/node_modules/vite/dist/node/chunks/dep-c9998dc6.js:45537:17)
at setFsWatchListener (/app/node_modules/vite/dist/node/chunks/dep-c9998dc6.js:45584:15)
at NodeFsHandler$1._watchWithNodeFs (/app/node_modules/vite/dist/node/chunks/dep-c9998dc6.js:45739:14)
at NodeFsHandler$1._handleDir (/app/node_modules/vite/dist/node/chunks/dep-c9998dc6.js:45975:19)
at runMicrotasks ()
at processTicksAndRejections (node:internal/process/task_queues:96:5)
at async NodeFsHandler$1._addToNodeFs (/app/node_modules/vite/dist/node/chunks/dep-c9998dc6.js:46025:16)

FSWatcher实例触发'error'事件位置：
at FSWatcher._handleError (/app/node_modules/vite/dist/node/chunks/dep-c9998dc6.js:47233:10)
at NodeFsHandler$1._addToNodeFs (/app/node_modules/vite/dist/node/chunks/dep-c9998dc6.js:46053:18)
at runMicrotasks ()
at processTicksAndRejections (node:internal/process/task_queues:96:5) {
errno: -28,
syscall: 'watch',
code: 'ENOSPC',
path: '/app/vendor/league/commonmark/src/Extension/CommonMark/Delimiter/Processor',
filename: '/app/vendor/league/commonmark/src/Extension/CommonMark/Delimiter/Processor'
}

报错本质是系统分配的文件监听器数量耗尽，Vite尝试监听vendor目录下的文件时超出限额。

1. 修正生产环境部署逻辑（根本解决，Heroku环境必做） #

Heroku生产环境禁止运行Vite开发服务，开发服务的文件监听、热更新逻辑只适合本地开发使用，生产环境的正确流程是提前构建静态资源：

• 在Heroku构建阶段执行npm run build，Vite会把编译后的JS、CSS等静态资源输出到public目录，由Laravel直接托管
• 检查Procfile配置，web进程只需要配置PHP web服务启动命令，不要把vite/vite dev作为常驻进程启动，参考配置：

  web: heroku-php-apache2 public/
  

2. 临时调试场景优化（仅用于非生产环境调试） #

如果确实需要在Heroku环境临时启动Vite开发服务做调试，通过缩小Vite监听范围减少监听器占用：
在项目根目录vite.config.js中添加忽略规则，排除不需要监听的目录：

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/css/app.css', 'resources/js/app.js'],
            refresh: true,
        }),
    ],
    server: {
        watch: {
            ignored: [
                '**/vendor/**',
                '**/storage/**',
                '**/bootstrap/cache/**'
            ]
        }
    }
});

配置后Vite不会监听Laravel第三方依赖、缓存、日志目录下的文件，监听器占用会大幅降低。

3. 自有Linux服务器同类报错处理 #

如果是在自己可控的Linux服务器（非Heroku）遇到相同报错，直接调高系统inotify监听器上限即可，执行命令：

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

Heroku dyno是只读容器环境，没有修改内核参数的权限，该方法在Heroku上无效。

4. Heroku资源规格检查 #

免费层Heroku dyno本身有严格的资源配额限制，inotify上限远低于标准付费dyno，不要在免费dyno上运行任何需要文件监听的常驻服务。

内容的提问来源于stack exchange，提问作者sarthak_dev