sublime text 本身不支持 gulp，必须通过 wbond 维护的 gulp 插件调用项目本地 node_modules/.bin/gulp；插件不识别全局 gulp、npx 或 package.json scripts，且仅向上搜索 gulpfile.js，不递归扫描工作区。

Sublime Text 本身不支持 Gulp，必须靠 Gulp 插件（wbond 维护）调用你项目里已装好的本地 gulp 可执行文件；它不认全局安装的 gulp，也不走 npx 或 package.json scripts。

确认项目中已正确安装本地 gulp

插件只找 node_modules/.bin/gulp（Linux/macOS）或 node_modules\.bin\gulp.cmd（Windows），路径错一个字符都会报 gulp command not found。

• 在项目根目录运行：npm install --save-dev gulp gulp-cli（gulp-cli 必须显式安装，否则 gulp v4+ 无法启动）
• 检查是否存在：ls node_modules/.bin/gulp（macOS/Linux）或 dir node_modules\.bin\gulp.*（Windows）
• 若用 pnpm：默认硬链接可能让 Sublime 找不到 .bin 下的可执行文件，加 "preferSymlink": true 到 .pnpmrc
• 若用 yarn（v1）：确保没启用 flat 模式；yarn v3+ 的 .yarn/bin 不被插件识别，建议降级或改用 npm/pnpm

安装并验证 Gulp 插件是否加载成功

插件名就是 Gulp，不是 SublimeGulp、GulpBuild 等变体；它依赖 Package Control，且仅兼容 Sublime Text 4（API v4）及以上。

Sublime Text Build Linux版

Sublime Text Linux x86-64 deb 安装包。官方也提供 rpm、tar.xz 和软件源安装方式。

下载

• 按 Ctrl+Shift+P（Windows/Linux）或 Cmd+Shift+P（macOS），输入 Package Control: Install Package → 回车 → 搜 Gulp → 安装
• 重启 Sublime Text，看右下角状态栏是否显示 Gulp 字样；不显示=插件未加载
• 若 Console（Ctrl+`）报 ImportError 或 No module named 'sublime'，说明插件未适配当前 ST 版本——别折腾旧版插件，直接换用轻量替代 SublimeLinter-gulp（仅做 task 检查，不执行）

运行任务时提示 “No tasks found” 或找不到 gulpfile.js

插件默认只从当前打开的文件所在目录向上逐级查找 gulpfile.js，不会扫描整个工作区，也不会进子目录；多根工作区、monorepo 子包、symbolic link 目录都容易踩坑。

• 确保当前视图中至少有一个文件属于目标项目（比如打开了 src/index.js），否则插件无法推断工作路径
• 手动指定路径：按 Ctrl+Shift+P → 输入 Gulp: Set Gulp File Path → 填绝对路径，如 /Users/you/project/gulpfile.js
• exports.default 会被识别为 default 任务；但 exports['build:css'] 这种带冒号/空格的命名，插件不支持——必须改用 exports.buildCss 或在 gulp.task() 中显式注册
• 任务名区分大小写，build 和 Build 是两个不同任务

任务失败但控制台无输出，怎么 debug？

Sublime 的 Gulp 插件会捕获 stdout/stderr 并显示在输出面板，但对未处理的 Promise rejection、process.exit(1)、同步 throw 之外的异常响应很弱——经常只显示 Task failed 而无堆栈。

• 先在终端手动运行：npx gulp your-task-name，看真实错误是否暴露
• 在 gulpfile.js 中给 task 加 on('error', console.error)，例如：return gulp.src(...).pipe(...).on('error', console.error)
• 避免在 task 中直接 throw new Error()；改用 Promise.reject() 或 cb(new Error())（callback 形式）保证插件能捕获
• 注意：插件不支持 async/await 语法糖的顶层错误传播，务必用 try/catch 包裹并传给 cb()

最常被忽略的是：插件根本没机会看到你 gulpfile.js 里的 console.log，除非你显式把日志 pipe 到 process.stdout；别指望靠打印调试，优先用终端复现 + 错误监听。