运行npm run gulp报primordials is not defined错误怎么解决

错误原因 #

primordials is not defined错误核心是 Gulp 3.x版本与Node.js 12及以上版本不兼容。Gulp 3依赖的旧版graceful-fs调用了Node.js高版本已经移除的primordials内部API，你当前使用的Node.js v17.0.1远高于兼容阈值，因此触发报错。

可行解决方案 #

方案1：升级Gulp到4.x版本（长期兼容，最推荐） #

适合愿意调整旧gulpfile语法的场景，解决后不会再出现版本兼容问题：

• 先卸载项目本地旧版gulp和全局gulp-cli：

npm uninstall gulp gulp-cli
npm uninstall -g gulp-cli

• 安装最新版全局gulp-cli和项目本地gulp：

npm install -g gulp-cli
npm install --save-dev gulp@4

• 适配gulpfile.js语法：Gulp 4要求所有串行/并行任务用gulp.series()、gulp.parallel()包裹，修改原有任务定义即可。

方案2：降级Node.js到v11.x及以下版本 #

适合不想修改现有gulpfile代码的场景，可通过nvm管理多版本Node.js无需卸载当前版本：

• 安装兼容Gulp3的最后一个Node.js版本：

nvm install 11.15.0

• 切换到该版本后重新安装依赖：

nvm use 11.15.0
rm -rf node_modules package-lock.json npm-shrinkwrap.json
npm install

• 执行npm run gulp即可正常运行。

方案3：强制锁定graceful-fs依赖版本 #

无需修改Node.js和Gulp版本，适合你之前配置npm-shrinkwrap不生效的场景（要求npm版本≥8.3.0）：

• 打开项目package.json文件，新增overrides字段强制锁定graceful-fs到兼容版本：

{
  "name": "gulp-tutorial",
  "version": "1.0.0",
  // 保留你原有配置不变，新增下面的overrides字段
  "overrides": {
    "graceful-fs": "^4.2.11"
  }
}

• 删除原有依赖文件和缓存：

rm -rf node_modules package-lock.json npm-shrinkwrap.json

• 重新安装依赖后运行gulp即可：

npm install
npm run gulp

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