运行npm脚本如何忽略全局node_modules仅使用项目本地依赖

npm 本身没有给npm run提供--local-only类参数，该参数仅对npm install等依赖安装命令生效，作用是安装阶段跳过全局关联，无法控制脚本运行时的模块搜索逻辑。

全局模块被异常加载，本质是Node.js模块解析规则默认会读取NODE_PATH环境变量指定的全局搜索路径，同时会递归向上遍历所有父级目录的node_modules文件夹，最终扫到用户目录下的全局模块。可以通过以下方案解决，配置仅对当前项目/当前执行生效，完全不影响其他场景使用全局npm包：

• 单次运行临时屏蔽全局模块
  运行脚本前手动将NODE_PATH置空即可，命令仅对当前单次执行生效，不会修改任何全局配置：

  # macOS/Linux 系统
  NODE_PATH="" npm run start
  
  # Windows cmd 环境
  set NODE_PATH="" && npm run start
  
  # Windows PowerShell 环境
  $env:NODE_PATH=""; npm run start
  

• 项目内固化配置，每次运行自动屏蔽全局路径
  直接修改项目package.json里的scripts配置，提前将环境变量置空，后续正常执行npm run start就会自动生效：

  {
    "scripts": {
      // macOS/Linux 直接配置即可
      "start": "NODE_PATH='' node 项目入口文件路径",
      // 如需兼容全平台，先在项目本地安装cross-env：npm i cross-env -D
      // 再将脚本改写为 "start": "cross-env NODE_PATH='' node 项目入口文件路径"
    }
  }
  

配置有效性验证 #

在项目目录下执行以下命令打印Node的模块搜索路径，如果输出中没有用户目录下的全局node_modules路径（例如示例中的/Users/Bob/node_modules），即说明配置生效：

# 对应临时屏蔽方案的验证命令
NODE_PATH="" node -e "console.log(module.paths)"

注意：配置生效后如果出现「找不到模块」类报错，说明项目本身漏装了对应依赖，直接执行npm i 缺失的包名将依赖安装到项目本地即可。正规项目本就不应该隐式依赖全局安装的包，将所有运行依赖声明在本地package.json中，也能避免其他协作者拉取代码后无法正常启动的问题。

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