Gulp动态生成任务及series使用异常：异步完成信号问题求助

问题背景 #

开发的应用需适配3个环境、渲染5个模板，任务执行流程如下：

default:
  - env 1
    - template 1
    - template 2
    ...
  - env 2
    - template 1
    - template 2
    ...

需要动态生成任务（新增模板时自动扩展），但始终遭遇「以下任务未完成」错误——即使让renderTemplate返回Promise，日志显示该函数甚至未被调用。

测试代码 #

const {
    src,
    dest,
    series
} = require('gulp');
const {
    setTimeout
} = require('timers/promises')

const env = ['1', '2', '3'];
const template = ['1', '2', '3'];

function renderEnv(info) {
    console.debug('renderEnv', info);
    const funcs = template.map(n => mod(renderTemplate, n));
    return series(...funcs);
}

function renderTemplate(info) {
    console.debug('renderTemplate', info);
}

// 绑定参数并保留函数名称
function mod(func, args, name) {
    const argArray = Array.isArray(args) ? args : [args];
    const newFunc = func.bind(null, ...argArray);
    newFunc.displayName = name || func.name;
    return newFunc;
}

function defaultFunc() {
    const funcs = env.map(n => mod(renderEnv, n));
    return series(...funcs)
}

exports.default = series(defaultFunc());

报错信息 #

Starting 'default'...
Starting 'renderEnv'...
renderEnv 1
The following tasks did not complete: default, <series>, renderEnv
Did you forget to signal async completion?

问题原因与解决方案 #

核心问题 #

1. renderEnv返回值不符合Gulp要求：Gulp任务函数不能直接返回series()生成的任务组合。Gulp要求任务函数要么同步执行完成，要么通过回调、Promise、流或子进程标记异步完成。当前renderEnv返回的是任务组合函数，Gulp无法识别，因此判定任务未完成。
2. 任务嵌套层级混乱：defaultFunc已经返回了series组合的任务，但你又将其包裹在另一层series()中传给exports.default，导致Gulp无法正确解析执行流程。

修复步骤 #

步骤1：修改renderEnv，执行任务组合并返回结果

将renderEnv改为直接执行模板任务组合，返回其执行结果：

function renderEnv(info) {
    console.debug('renderEnv', info);
    const funcs = template.map(n => mod(renderTemplate, n));
    // 执行series组合的任务并返回结果
    return series(...funcs)();
}

步骤2：修正exports.default的嵌套问题

defaultFunc已返回正确的任务组合，无需再包裹series()：

exports.default = defaultFunc();

步骤3：标记异步任务完成

如果renderTemplate包含异步操作（如文件读写），需明确标记完成：

• 用Promise实现：

  async function renderTemplate(info) {
      console.debug('renderTemplate', info);
      // 模拟异步渲染操作
      await setTimeout(100);
  }
  

• 用回调实现：

  function renderTemplate(info, done) {
      console.debug('renderTemplate', info);
      // 模拟异步操作
      setTimeout(() => done(), 100);
  }
  

完整修复代码 #

const {
    src,
    dest,
    series
} = require('gulp');
const {
    setTimeout
} = require('timers/promises')

const env = ['1', '2', '3'];
const template = ['1', '2', '3'];

function renderEnv(info) {
    console.debug('renderEnv', info);
    const funcs = template.map(n => mod(renderTemplate, n));
    return series(...funcs)();
}

async function renderTemplate(info) {
    console.debug('renderTemplate', info);
    // 模拟异步渲染操作
    await setTimeout(100);
}

function mod(func, args, name) {
    const argArray = Array.isArray(args) ? args : [args];
    const newFunc = func.bind(null, ...argArray);
    newFunc.displayName = name || func.name;
    return newFunc;
}

function defaultFunc() {
    const funcs = env.map(n => mod(renderEnv, n));
    return series(...funcs);
}

exports.default = defaultFunc();

验证结果 #

执行修复后的代码，日志会按预期依次输出各环境与模板任务，最终显示任务完成：

Starting 'default'...
Starting 'renderEnv'...
renderEnv 1
Starting 'renderTemplate'...
renderTemplate 1
Starting 'renderTemplate'...
renderTemplate 2
Starting 'renderTemplate'...
renderTemplate 3
Starting 'renderEnv'...
renderEnv 2
...（后续环境与模板任务依次执行）
Finished 'default' after XX ms

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