本文介绍如何在 Gulp 4 中正确配置 watch，使其仅对被修改的单个 CSS/SCSS 文件触发 lint、编译与浏览器重载流程，避免全量检查导致的冗余输出和性能损耗。核心在于规避 chokidar 原生事件中无法直接执行 series() 的限制，并借助 gulp-cached 实现精准增量处理。
本文介绍如何在 gulp 4 中正确配置 `watch`，使其仅对被修改的单个 css/scss 文件触发 lint、编译与浏览器重载流程，避免全量检查导致的冗余输出和性能损耗。核心在于规避 chokidar 原生事件中无法直接执行 `series()` 的限制，并借助 `gulp-cached` 实现精准增量处理。
在 Gulp 4 中，watch() 返回的是底层 chokidar 实例，它不支持异步任务队列（如 series）的直接调用——这也是你第二个示例失效的根本原因：.on('all', ...) 回调中调用 series(compileCSS, reload) 不会自动执行，因为 series() 返回的是一个可执行任务函数，而非立即运行的任务；它必须被显式调用（如 series(...)(done)），且需符合 Gulp 的异步约定（接受 done 回调或返回 Promise/Stream）。
✅ 正确做法是：将 lint、编译、重载封装为独立、可复用的 Gulp 任务，并在 watch 回调中按需触发它们，同时利用缓存机制确保 lint 仅作用于变更文件。
以下是推荐的完整实现方案：
✅ 步骤一：安装必要依赖
npm install --save-dev gulp gulp-stylelint gulp-cached gulp-sass browser-sync
✅ 步骤二：定义带缓存的增量 lint 任务
const { src, series } = require('gulp');
const stylelint = require('gulp-stylelint');
const cache = require('gulp-cached');
function lintCSS() {
return src(config.path.scss)
.pipe(cache('lint-css')) // ✅ 仅处理本次修改且未被缓存的文件
.pipe(stylelint({
reporters: [{ formatter: 'string', console: true }]
}));
}
?
gulp-cached会为每个文件生成哈希指纹，仅当文件内容变更时才通过管道——这天然实现了“只 lint 修改文件”。
✅ 步骤三：定义编译与重载任务（保持原有逻辑）
function compileCSS() {
return src(config.path.scss)
.pipe(sass().on('error', sass.logError))
.pipe(dest(config.path.css));
}
function reload() {
return browserSync.stream();
}
✅ 步骤四：配置 watch —— 使用 gulp.series 触发完整流程
function watchCSS() {
// 启动监听
const watcher = watch(config.path.scss);
// 每次文件变更时，依次执行 lint → compile → reload
watcher.on('change', (path) => {
console.log(`→ Changed: ${path}`);
// 手动顺序执行（注意：需返回 Promise 或调用 done）
return series(lintCSS, compileCSS, reload)();
});
// 可选：对新增/删除文件也响应（如需）
watcher.on('add', (path) => console.log(`+ Added: ${path}`));
watcher.on('unlink', (path) => console.log(`- Removed: ${path}`));
}
exports.watchCSS = watchCSS;
⚠️ 关键注意事项：
-
不要在
.on()回调里直接写series(task1, task2)()：虽然语法可行，但 Gulp 4 的series()返回函数需明确调用，且若任一任务异步失败（如 lint 报错），可能中断后续流程。建议将整个流程封装为一个新任务：const lintCompileReload = series(lintCSS, compileCSS, reload); watcher.on('change', () => lintCompileReload()); -
cache()的命名空间（如'lint-css'）需唯一，避免与其他缓存冲突； - 若需严格「仅 lint 当前变更文件」（而非所有变更后未缓存的文件），可进一步结合
gulp-filter+path判断，但通常cache已满足绝大多数开发场景； - 确保
browserSync已初始化（如browserSync.init({...})），否则reload()将静默失败。
✅ 最终效果
终端输出简洁清晰：
→ Changed: src/styles/main.scss √ stylelint: src/styles/main.scss (no errors) [14:22:36] Finished 'lintCSS' after 123 ms [14:22:36] Finished 'compileCSS' after 89 ms [14:22:36] Finished 'reload' after 5 ms
此方案兼顾准确性、可维护性与调试友好性，是 Gulp 4 中实现「精准增量构建」的标准实践。
