升级Gulp 5与Node.js 20后BrowserSync抛出AggregateError求助

以下是针对你遇到的问题的具体修复步骤和代码调整：

1. 修复异步任务的回调时机 #

你的serve函数中，browserSync.init是异步操作，原代码直接调用done()会导致任务在初始化完成前就标记为完成，引发异步错误。修改为：

function serve(done) {
  browserSync.init({
    proxy: 'mysite.ddev.site',
    injectChanges: true
  }, done); // 把done作为初始化完成的回调
}

2. 调整watchTask的实现 #

Gulp 5中watch返回的是持续运行的任务，不需要手动调用done()，直接返回watch结果即可：

function watchTask() {
  return watch('css/scss/**/*.scss', series(cssTask, reload));
}

3. 添加全局错误捕获定位问题 #

AggregateError通常包含多个具体错误，添加以下代码可以打印出详细错误信息，方便调试：

// 放在gulpfile最顶部
process.on('unhandledRejection', (err) => {
  console.error('Unhandled Rejection:', err);
  if (err instanceof AggregateError) {
    console.error('具体错误列表:', err.errors);
  }
});

4. 更新依赖到兼容版本 #

确保所有依赖包支持Gulp 5和Node.js 20，执行以下命令更新：

npm update gulp gulp-sass gulp-sourcemaps browser-sync

或直接修改package.json后执行npm install：

{
  "devDependencies": {
    "browser-sync": "^2.29.3",
    "gulp": "^5.0.0",
    "gulp-sass": "^5.1.0",
    "gulp-sourcemaps": "^3.0.0",
    "sass": "^1.70.0"
  }
}

5. 明确Sourcemaps输出路径 #

避免路径歧义，修改cssTask中的sourcemaps.write()：

.pipe(sourcemaps.write('./')) // 明确输出到css目录下

修改后的完整gulpfile代码 #

const { src, dest, watch, series } = require('gulp');
const sass = require('gulp-sass')(require('sass'));
const sourcemaps = require('gulp-sourcemaps');
const browserSync = require('browser-sync').create();

// 全局错误捕获，定位具体问题
process.on('unhandledRejection', (err) => {
  console.error('Unhandled Rejection:', err);
  if (err instanceof AggregateError) {
    console.error('具体错误列表:', err.errors);
  }
});

function reload(done) {
  browserSync.reload();
  done();
}

function serve(done) {
  browserSync.init({
    proxy: 'mysite.ddev.site',
    injectChanges: true
  }, done);
}

function watchTask() {
  return watch('css/scss/**/*.scss', series(cssTask, reload));
}

function cssTask() {
  return src('css/scss/**/*.scss')
    .pipe(sourcemaps.init())
    .pipe(sass({ outputStyle: 'compressed' }).on('error', sass.logError))
    .pipe(sourcemaps.write('./'))
    .pipe(dest('css/'))
    .pipe(browserSync.stream());
}

exports.default = series(serve, watchTask);

额外排查点 #

• 确认代理地址mysite.ddev.site可以正常访问，无法连接会导致browserSync初始化失败
• 检查文件权限，Node.js 20对文件系统的权限控制更严格，确保css/目录有读写权限

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