Docker环境Node.js非交互会话无法找到已安装nodemon模块

问题场景 #

• 运行环境：基于官方node:latest镜像启动容器，将本地存放项目文件的磁盘目录挂载到容器内/app路径，依赖nodemon实现容器外编辑代码时服务自动重启的热更新能力
• 异常触发背景：该套配置2年前可正常运行，近期升级项目依赖（适配新运行环境、修复高危安全漏洞）后出现稳定复现的异常
• 异常表现：
  • 容器启动阶段自动执行nodemon相关命令、手动进入容器命令行调用Node.js运行nodemon指令时，均抛出MODULE_NOT_FOUND错误，提示无法找到路径/app/nodemon对应的模块
  • 进入容器shell启动Node.js交互式会话（REPL），执行require("nodemon")可正常加载模块，无任何报错
• 已完成排查项：
  • 确认执行命令时当前工作目录为/app
  • 确认/app/node_modules目录下存在已安装完成的nodemon包
  • 手动配置NODE_PATH环境变量指向/app/node_modules后问题仍复现
  • 容器启动时执行全新依赖安装流程，问题可在无缓存的全新node:latest容器中100%复现，2年前同启动脚本、同docker-compose配置可正常运行
  • 已收集全量复现材料：错误执行日志、目录结构信息、package.json配置、nodemon包信息查询结果、容器启动依赖安装shell脚本、docker-compose.yml配置文件

根因分析 #

1. 核心错误为nodemon调用方式不符合Node.js新版本的参数解析规则：
   当命令行执行node nodemon <入口文件>时，Node.js会将传入的nodemon参数识别为相对于当前工作目录的文件路径，直接查找/app/nodemon实体文件，不会触发node_modules目录的模块查找逻辑，也不会读取NODE_PATH配置查找模块，因此抛出找不到文件的错误。
   而Node.js REPL环境下执行require("nodemon")时，会遵循标准模块解析规则，遍历各级node_modules目录、NODE_PATH路径查找对应包，因此可以正常加载。
2. 旧配置可运行的原因：
   早期Node.js 16及更早版本存在未文档化的参数兼容逻辑，当传入的命令行参数不是有效相对路径时，会尝试匹配node_modules下的包作为入口文件；该逻辑在Node.js 18+版本的重构中被移除，因此旧的错误写法升级后失效。

解决方案 #

按以下步骤调整即可修复：

1. 修正nodemon的调用写法，不要使用node nodemon的错误格式，以下三种方案任选其一：
   • 方案一（最稳定，无环境依赖）：直接调用node_modules下的可执行文件
     启动命令直接写nodemon二进制文件的完整路径：

     /app/node_modules/.bin/nodemon 你的项目入口文件.js
     

   • 方案二（推荐，符合Node.js项目常规规范）：通过npm scripts调用
     在项目package.json中配置脚本：

     {
       "scripts": {
         "dev": "nodemon 你的项目入口文件.js"
       }
     }
     

     容器启动时执行npm run dev即可，npm执行脚本时会自动将node_modules/.bin加入临时环境变量PATH，无需额外配置即可找到nodemon命令。
   • 方案三：通过npx调用
     npx会自动查找本地node_modules下安装的可执行文件，启动命令写为：

     npx nodemon 你的项目入口文件.js
     

2. （可选，解决热更新不触发的兼容问题）
   由于Docker跨系统挂载目录（Windows/macOS宿主机挂载、非root用户运行Linux容器）时，默认的文件系统事件通知可能无法正常传递到容器内，nodemon会出现文件修改后不自动重启的问题，启动时增加-L参数启用兼容的 legacy 监听模式即可：

   npx nodemon -L 你的项目入口文件.js
   

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