gulp 5 流式构建系统完全指南:从零编写 gulpfile 到增量构建与 ESM 实践

原创2026-09-18 13:41:071,632 阅读
文章标签:构建工具CLI

gulp 5 流式构建系统完全指南:从零编写 gulpfile 到增量构建与 ESM 实践

导读:gulp 是一个以 Node.js 流(Stream)为核心、用于自动化开发工作流中重复性耗时任务的流式构建系统。本文以本仓库 README.md 为骨架,完整讲解 gulp 的核心定位、安装步骤、CommonJS 与 ESM 两种 gulpfile 编写范式,以及基于 gulp.src 的 since 选项与 gulp.lastRun 的增量构建方案,并结合仓库源码(index.js、package.json、test/index.test.js)逐层剖析其实现原理。读完本文,你将能够独立编写一套可运行的 gulp 构建流程,并理解任务编排、流式管道与增量优化的底层机制。

gulp 是什么:一个"流式"构建系统

仓库 README 将 gulp 定位为 The streaming build system(流式构建系统),并从四个维度概括了它的设计哲学:

  • 自动化(Automation):gulp 是一套帮助你自动化开发工作流中那些繁琐、耗时的任务的工具包。无论是压缩图片、转译 JavaScript、编译样式表,还是清理构建产物,都可以通过定义任务让 gulp 代劳。
  • 平台无关(Platform-agnostic):gulp 的集成能力已经内建到几乎所有主流 IDE 中,并且被广泛用于 PHP、.NET、Node.js、Java 等多种平台的技术栈。
  • 强大的生态(Strong Ecosystem):你可以直接使用 npm 上任何包完成任何需求,此外还有超过 3000 个经过筛选的插件专门用于流式文件转换(如 gulp-less、gulp-babel、gulp-uglify 等)。
  • 简单(Simple):gulp 只暴露了极小的 API 面(src、dest、watch、series、parallel 等),易于学习、易于使用。

这种"小 API 面 + 流式管道"的设计,与传统的任务运行器(如 Grunt 的配置驱动模型)形成鲜明对比:gulp 是代码驱动的,gulpfile 本质上就是一个普通的 Node.js 程序,你可以自由组合流、Promise 和回调。

安装与快速开始

仓库 README 的安装说明指向 Quick Start 指南。完整流程如下:

1. 检查 Node.js、npm 与 npx 环境:

node --version
npm --version
npx --version

gulp 5 对运行时有明确要求,见 package.json 中的 engines 字段:Node.js 版本必须 >= 10.13.0。

2. 全局安装 gulp 命令行工具(注意:是 gulp-cli,而不是 gulp 本身):

npm install --global gulp-cli

如果你之前全局安装过 gulp,请先执行 npm rm --global gulp 再继续,以免旧版全局包与新 CLI 产生冲突。

3. 创建项目目录与 package.json:

npx mkdirp my-project
cd my-project
npm init

4. 在 devDependencies 中安装 gulp 包:

npm install --save-dev gulp

5. 验证版本:

gulp --version

6. 创建 gulpfile 并测试:在项目根目录创建 gulpfile.js:

function defaultTask(cb) {
  // place code for your default task here
  cb();
}

exports.default = defaultTask

在项目目录下直接运行 gulp,默认任务就会执行;运行 gulp <task> <othertask> 则可以一次执行多个任务。

CLI 与本地包的职责划分

从仓库结构可以清晰看到这种"全局 CLI + 本地包"的分离设计:

  • bin/gulp.js 是本地 gulp 包的可执行入口,只有一行 require('gulp-cli')();——真正的命令行解析、任务查找与执行逻辑由独立的 gulp-cli 包承担;
  • package.json 通过 "bin": { "gulp": "./bin/gulp.js" } 将 gulp 命令绑定到该入口。

因此,全局安装 gulp-cli 提供 gulp 命令,本地安装 gulp 提供实际的流式 API 与任务定义,二者配合构成了完整的运行链路。

示例 gulpfile.js 逐段拆解

README 提供了一个贯穿样式与脚本两条构建链路的完整示例(CommonJS 版本)。这是理解 gulp 工作方式的最佳入口,下面逐段展开并补充注释。

引入依赖并定义路径

var gulp = require('gulp');
var less = require('gulp-less');
var babel = require('gulp-babel');
var concat = require('gulp-concat');
var uglify = require('gulp-uglify');
var rename = require('gulp-rename');
var cleanCSS = require('gulp-clean-css');
var del = require('del');

var paths = {
  styles: {
    src: 'src/styles/**/*.less',
    dest: 'assets/styles/'
  },
  scripts: {
    src: 'src/scripts/**/*.js',
    dest: 'assets/scripts/'
  }
};

其中 src/styles/**/*.less 与 src/scripts/**/*.js 是 glob 匹配模式:** 递归匹配任意层级目录,* 匹配文件名片段。glob 语法与规则可参考 Explaining Globs。

清理任务:返回 Promise 即可

function clean() {
  // You can use multiple globbing patterns as you would with `gulp.src`,
  // for example if you are using del 2.0 or above, return its promise
  return del([ 'assets' ]);
}

这段代码揭示了一条重要规则(README 中特别用注释强调):并非所有任务都必须使用流——gulpfile 只是一个普通的 Node.js 程序,你可以使用 npm 上的任何包。但任务必须满足以下三种异步完成约定之一:

  1. 返回一个 Stream;
  2. 返回一个 Promise(如 del 2.0 及以上版本返回的 Promise);
  3. 接受一个 callback 并在完成时调用它。

关于异步完成的细节可参考 Async Completion。

样式任务:less → 压缩 → 重命名 → 输出

function styles() {
  return gulp.src(paths.styles.src)
    .pipe(less())
    .pipe(cleanCSS())
    // pass in options to the stream
    .pipe(rename({
      basename: 'main',
      suffix: '.min'
    }))
    .pipe(gulp.dest(paths.styles.dest));
}

这是 gulp 的核心模式——流式管道(pipeline):

  • gulp.src(glob) 读取匹配的文件并转换为 Vinyl 文件对象流;
  • 一系列 .pipe() 将每个插件串接起来,按顺序对文件做转换(编译、压缩、重命名);
  • gulp.dest(path) 在管道末端把处理后的文件写入目标目录,同时保持目录结构。

注意 rename 接收的是一个选项对象(basename: 'main'、suffix: '.min'),这正是 README 注释所说的"pass in options to the stream"——插件通过选项对象进行配置。

脚本任务:sourcemaps 开启 → Babel → 压缩 → 合并

function scripts() {
  return gulp.src(paths.scripts.src, { sourcemaps: true })
    .pipe(babel())
    .pipe(uglify())
    .pipe(concat('main.min.js'))
    .pipe(gulp.dest(paths.scripts.dest));
}

这里展示了 gulp.src 的第二个参数——选项对象:{ sourcemaps: true } 会为管道内生成源映射(source map),使压缩后的代码仍可调试。随后 babel() 将 ES6+ 转译为 ES5,uglify() 压缩,concat('main.min.js') 合并为单个文件。

gulp.src 支持更多选项(如 since、base、ignore、allowEmpty 等),完整列表见 src API 文档。

监听任务:文件变化触发重建

function watch() {
  gulp.watch(paths.scripts.src, scripts);
  gulp.watch(paths.styles.src, styles);
}

gulp.watch(glob, task) 监视匹配文件的变化,一旦发生增删改就触发对应任务。文件监听、事件语义与高级用法(如 add/change/unlink 事件)可参考 watch API 文档 与 Watching Files。

任务编排:series 与 parallel

var build = gulp.series(clean, gulp.parallel(styles, scripts));

gulp 4 引入的任务编排模型是 README 的重点:

  • gulp.series(task1, task2, ...):串行执行任务,前一个完成后再执行下一个;
  • gulp.parallel(task1, task2, ...):并行执行任务,互不等待(由于 Node 单线程特性,实际是并发启动各任务并等待全部完成);
  • 二者可以任意嵌套组合,例如 build 的含义是:先清理,再并行编译样式和脚本。

更复杂的串并行组合(如 gulp.series(clean, gulp.parallel(gulp.series(a, b), c)))会在多个任务同时引用同一任务时自动去重,详见 series 文档 与 parallel 文档。

用 exports 声明任务

exports.clean = clean;
exports.styles = styles;
exports.scripts = scripts;
exports.watch = watch;
exports.build = build;
/*
 * Define default task that can be called by just running `gulp` from cli
 */
exports.default = build;

gulp 4+ 使用 Node.js 原生的 CommonJS exports 模块导出来声明任务,而非旧版的 gulp.task('name', fn)。这样定义后:

  • 通过 gulp styles、gulp watch、gulp build 即可调用对应任务;
  • exports.default 是默认任务,直接运行 gulp 就会执行它(这里默认执行完整构建 build);
  • 导出的任务同样可以组合进 gulp.series / gulp.parallel(如 gulp.series(clean, gulp.parallel(styles, scripts)) 中的 clean、styles、scripts 都是前面定义并导出的函数)。

任务定义与导出语义可参考 Creating Tasks。

在 gulpfile 中使用最新 JavaScript 语法(ESM)

README 明确指出:gulp 提供了一个 ESM 包装器,只要把 gulpfile 命名为 gulpfile.mjs,或者在 package.json 中声明 "type": "module",就可以直接在 gulpfile 中使用 import 等 ESNext 语法。

从仓库源码看,这个 ESM 包装器就是 index.mjs:它从 CommonJS 入口 index.js 导入 gulp 实例,再将其 API(watch、task、series、parallel、registry、tree、lastRun、src、dest、symlink)逐一命名导出,同时保留默认导出。与之对应,package.json 的 exports 字段为不同加载方式指定了不同入口:import 走 ./index.mjs,require 走 ./index.js。

下面是 README 提供的同一示例的 ESNext 版本:

import { src, dest, watch } from 'gulp';
import less from 'gulp-less';
import babel from 'gulp-babel';
import concat from 'gulp-concat';
import uglify from 'gulp-uglify';
import rename from 'gulp-rename';
import cleanCSS from 'gulp-clean-css';
import {deleteAsync} from 'del';

const paths = {
  styles: {
    src: 'src/styles/**/*.less',
    dest: 'assets/styles/'
  },
  scripts: {
    src: 'src/scripts/**/*.js',
    dest: 'assets/scripts/'
  }
};

/*
 * For small tasks you can export arrow functions
 */
export const clean = () => deleteAsync([ 'assets' ]);

/*
 * You can also declare named functions and export them as tasks
 */
export function styles() {
  return src(paths.styles.src)
    .pipe(less())
    .pipe(cleanCSS())
    // pass in options to the stream
    .pipe(rename({
      basename: 'main',
      suffix: '.min'
    }))
    .pipe(dest(paths.styles.dest));
}

export function scripts() {
  return src(paths.scripts.src, { sourcemaps: true })
    .pipe(babel())
    .pipe(uglify())
    .pipe(concat('main.min.js'))
    .pipe(dest(paths.scripts.dest));
}

 /*
  * You could even use `export as` to rename exported tasks
  */
function watchFiles() {
  watch(paths.scripts.src, scripts);
  watch(paths.styles.src, styles);
}
export { watchFiles as watch };

const build = gulp.series(clean, gulp.parallel(styles, scripts));
/*
 * Export a default task
 */
export default build;

这段代码与 CommonJS 版本一一对应,额外展示了三种 ESM 特有的写法:

  • 用箭头函数直接导出简单任务:export const clean = () => deleteAsync([ 'assets' ]);
  • 用 export function 导出命名函数任务;
  • 用 export { watchFiles as watch } 这种重命名导出,把内部函数 watchFiles 作为名为 watch 的任务暴露——这样 gulp watch 就能直接调用它。

两种模块格式都能被 CLI 正确加载

仓库测试 test/index.test.js 分别对 gulpfile.cjs(CommonJS 显式扩展名)与 gulpfile.mjs(ESM 显式扩展名)执行了真实 CLI 调用,并断言退出码为 0、stdout 包含对应文件名、stderr 为空。对应的最小 gulpfile 位于 test/fixtures/gulpfiles/cjs/gulpfile.cjs 与 test/fixtures/gulpfiles/mjs/gulpfile.mjs——后者甚至用 import gulp, { watch, task, series, ... } from 'gulp' 验证了命名导入的可用性,并断言 gulp 实例是 EventEmitter 的实例。这说明:只要 gulpfile 使用 .cjs / .mjs 扩展名(或在 package.json 里声明 "type": "module"),gulp 的 CLI 都能正确识别并加载。

增量构建:since 选项与 gulp.lastRun

README 的最后一个技术主题是增量构建(Incremental Builds)——只处理自上次构建以来发生变化(或被新增)的文件,从而显著缩短大项目的构建时间。实现它只需两个 API 配合:

  • gulp.src 的 since 选项:只让修改时间(mtime)晚于给定时间戳的文件进入管道;
  • gulp.lastRun(taskName):返回指定任务最近一次成功运行的时间戳(毫秒数)。

README 给出的完整示例:

const paths = {
  ...
  images: {
    src: 'src/images/**/*.{jpg,jpeg,png}',
    dest: 'build/img/'
  }
}

function images() {
  return gulp.src(paths.images.src, {since: gulp.lastRun(images)})
    .pipe(imagemin())
    .pipe(gulp.dest(paths.images.dest));
}

function watch() {
  gulp.watch(paths.images.src, images);
}

运行逻辑如下:

  1. 首次执行 images 任务时,gulp.lastRun(images) 尚无记录,返回一个远古时间戳,因此所有图片都会进入管道被压缩;
  2. 任务成功后,gulp 在内存中记录该任务的完成时间;
  3. 在 watch 模式下第二次执行 images 任务时,since 只放行上次构建之后修改过的图片,imagemin() 仅处理这些增量文件,其余图片直接跳过。

README 特别给出了两条重要限制(必须牢记,否则会踩坑):

  • 任务运行时间保存在内存中,gulp 进程退出即丢失——因此增量构建只在 watch 连续运行期间有效,冷启动构建仍然会全量处理;
  • 只有 watch 触发的第二次及后续运行才能节省时间——第一次运行仍然需要完整处理所有文件。

gulp.lastRun 的完整参数说明(如如何指定带命名空间的组合任务)见 lastRun API 文档。

从源码看 gulp 的 API 是如何组织起来的

理解 gulp 的最小 API 面,最好的方式是直接阅读其核心实现 index.js,整个文件只有 55 行,却勾勒出了 gulp 的完整架构:

1. 类结构:Gulp 构造器调用 Undertaker.call(this),即继承自任务编排引擎 undertaker)。

2. 流式 I/O 来自 vinyl-fs:Gulp.prototype.src、dest、symlink 直接取自 vinyl-fs 模块(index.js),vinyl-fs 负责把 glob 解析成 Vinyl 文件流,并把流写回文件系统。这也解释了为什么 gulp 能以流为核心工作。

3. 文件监听来自 glob-watcher:Gulp.prototype.watch 底层委托给 glob-watcher 模块(index.js),并且内置了一个重要校验:如果传入的监听回调是字符串或数组,会直接抛出 Error('watching ...: watch task has to be a function (optionally generated by using gulp.parallel or gulp.series)')——这提醒我们 gulp.watch 的任务参数必须是函数,通常就是任务函数本身,或者是 gulp.parallel / gulp.series 生成的组合函数;另外,若第二个参数是函数,gulp 会将其识别为任务并自动用 this.parallel(task) 包装。

4. 所有 API 都被 bind 后挂到实例上:构造器中逐一对 watch、task、series、parallel 等做了 .bind(this)(index.js),目的是让这些方法可以被安全地解构出来单独使用(例如 const { src, dest, watch } = gulp),这正是 ESM 命名导入能够工作的前提。文件末尾 module.exports = inst 导出一个 Gulp 单例实例,这也是为什么 require('gulp') 直接就能用 gulp.src(...) 的原因。

测试 test/index.test.js 对 src、dest、symlink、watch、task、series、parallel、tree、lastRun、registry 十个 API 逐一断言了 hasOwnProperty,从测试层面固化了这份公共 API 清单。

更多资源

  • Getting Started 系列:从 Quick Start 开始,依次覆盖 gulpfile 编写、任务创建、异步完成、文件处理、glob 语法、插件使用与文件监听;
  • API 文档:src、dest、watch、series、parallel、registry、tree、lastRun、symlink 等全部接口的精确定义,其中 concepts 篇 概括了核心概念;
  • CLI 文档:介绍如何通过命令行调用任务、传递参数与使用编译器;
  • Writing a Plugin:如果现有插件无法满足需求,可参考该系列编写自己的 gulp 插件;
  • Recipes:社区贡献的常见场景配方(增量构建、多目录结构、watch 删除事件处理、Browserify 集成等);
  • FAQ:常见问题解答;
  • CONTRIBUTING.md:如果你想为项目本身做贡献,可参考其中的指引。
登录后查看全文
gulp