PhpStorm双击运行Gulp任务失败主因是gulpfile.js未正确加载或Node运行时不匹配；需本地安装gulp、匹配项目Node版本、Gulp 4+任务须显式处理异步完成、ES6写法需--harmony等参数或改.mjs后缀、多gulpfile须手动添加、任务名区分大小写且参数需yargs/minimist解析。
PhpStorm 里双击运行 Gulp 任务失败，90% 是因为 gulpfile.js 没被正确加载或 Node 运行时不匹配——不是插件没装，也不是 IDE 坏了，而是配置项填错了位置。
“Cannot find module 'gulp'” 的真实原因和解法
这个错误不是 PhpStorm 找不到全局 gulp-cli，而是它在执行时用当前项目路径去 require('gulp')，结果发现 node_modules/gulp 不存在。
- 必须本地安装
gulp：运行npm install --save-dev gulp（Gulp 4+ 要求），不能只装gulp-cli -
Node.js interpreter必须指向项目所用的 Node 版本（比如通过nvm切换的版本），不能选System default - 如果项目用了
pnpm或yarn，确保node_modules下真有gulp目录，别信pnpm list gulp的输出，直接ls node_modules/gulp看
Gulp 4+ 任务双击无响应？检查异步信号是否发出
双击后控制台卡在 Starting 'build'，然后超时退出，大概率是任务函数没正确结束。
- Gulp 4+ 不再自动识别
return stream以外的异步行为，fs.readFile、child_process.exec等都得显式处理 - 函数参数带
cb就必须调cb()；返回 Promise 就不能漏return；返回 Stream 就不能被中间.on('end', ...)拦截掉完成信号 - 写法示例：
exports.build = () => gulp.src('src/**').pipe(gulp.dest('dist'));✅；exports.build = () => { fs.copyFile(...); };❌（没返回、没回调、没 Promise）
ES6 写法的 gulpfile.js 在 PhpStorm 里不显示任务？加 --harmony 不够
仅加 --harmony 可能仍报 Unexpected token import，因为 Node 版本太低或模块解析方式不对。
立即学习“PHP免费学习笔记（深入）”；
- 确认 Node 版本 ≥ 14.18（
node -v），低于此版本import默认不可用 - 在运行配置的
Node options栏填完整参数：--harmony --experimental-specifier-resolution=node --no-warnings - 把
gulpfile.js改成.mjs后缀，并在package.json加"type": "module"，比硬塞--harmony更可靠 - 删掉
node_modules和package-lock.json，重装依赖，避免旧缓存干扰模块解析
多个 gulpfile.js 共存时，双击总跑错文件
PhpStorm 默认只扫描项目根目录下的 gulpfile.js。子目录里的（如 client/gulpfile.js）不会自动注册，双击只会执行根目录那个。
- 打开
Gulp工具窗口（View → Tool Windows → Gulp） - 点右上角
+（Add Gulpfile），手动选中子目录下的gulpfile.js - 新节点会显示完整路径，比如
client/gulpfile.js，下面的任务树完全独立 - 右键该节点 →
Reload tasks，确保改动实时生效；误删可用同样方式重新添加
最常被忽略的是：Gulp 任务名区分大小写，且不能含空格或特殊符号；Parameters 字段传参不会自动挂到 process.env，必须在 gulpfile.js 里用 yargs 或 minimist 显式解析——否则双击时看似传了 --env production，实际代码里读不到。
