全局安装Node.js CLI遇MODULE_NOT_FOUND错误求助（含复现步骤）

问题核心 #

全局安装基于ESM的Node.js CLI工具后，调用时出现模块找不到的错误，即便对应模块已安装在当前nvm版本的全局node_modules目录下。根源在于ESM模块解析逻辑、--require参数的模块查找路径，以及全局CLI的依赖管理方式。

解决方案 #

1. 移除不必要的实验性参数（针对当前测试案例） #

Node.js 18.13.0已稳定支持ESM和带assert {type: 'json'}的JSON导入，无需添加--experimental-modules参数，自然也不需要suppress-experimental-warnings模块。直接修改你的index.js：

#!/usr/bin/env node

import jsonContent from './jsonFile.json' assert { type: "json"};
console.log(jsonContent);

重新全局安装后，test2-cli即可正常运行。

2. 规范依赖管理（通用方案） #

如果你的CLI确实依赖第三方模块，必须将其添加到项目的dependencies中：

npm install suppress-experimental-warnings --save

执行全局安装时，npm会自动将依赖安装到CLI的全局目录下（如/home/bjam/.nvm/versions/node/v18.13.0/lib/node_modules/test2/node_modules/），Node执行CLI时会自动从这个路径查找模块，无需手动全局安装依赖。

3. 配置全局模块查找路径（针对必须使用全局模块的场景） #

若你需要使用全局安装的模块，可通过设置NODE_PATH环境变量让Node找到全局模块：

• 修改index.js的shebang，动态注入全局模块路径：

  #!/usr/bin/env NODE_PATH=$(npm root -g) node --require=suppress-experimental-warnings
  
  import jsonContent from './jsonFile.json' assert { type: "json"};
  console.log(jsonContent);
  

  npm root -g会自动输出当前Node版本的全局node_modules路径，避免硬编码路径导致nvm切换版本后失效。

4. 替换--require为ESM导入（通用优化） #

如果依赖模块支持ESM导入，直接在代码顶部导入替代--require参数：

#!/usr/bin/env node

import 'suppress-experimental-warnings';
import jsonContent from './jsonFile.json' assert { type: "json"};
console.log(jsonContent);

这种方式更符合ESM的规范，模块查找逻辑也更清晰。

nvm环境注意事项 #

• 全局安装CLI时，确保当前终端已激活正确的Node.js版本（通过node -v验证），避免依赖安装到其他版本的全局目录。
• 若切换nvm版本后出现问题，需重新全局安装CLI和对应的依赖。

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