Gulp 5 自定义注册表Custom Registries完全指南从共享任务到任务装饰器【免费下载链接】gulpA toolkit to automate enhance your workflow项目地址: https://gitcode.com/gh_mirrors/gu/gulp自定义注册表Custom Registries是 Gulp 任务系统task system中最具扩展性的能力之一它允许你把第三方注册表插拔进任务系统从而提供跨项目共享的任务或在任务被添加时对它们进行包装和增强。读完本文你将掌握注册表必须实现的四个方法及其调用时机、如何通过registry()正确注册实例、如何利用init()共享跨项目的通用任务以及如何通过重写set()为所有任务附加共享数据与装饰逻辑——所有内容都基于本仓库中 Gulp 5 的真实源码与官方 API 文档展开。什么是自定义注册表Gulp 的任务系统并非把任务硬编码在内部而是委托给一个注册表registry对象来存储和解析任务。默认情况下Gulp 使用 undertaker-registryGulp 4/5 的默认注册表实现来管理任务但你可以通过registry()将自定义注册表接入任务系统让它提供共享任务把多个项目都要用的clean、build等任务集中定义在一个注册表里一处维护、处处复用提供增强功能通过控制任务如何被加入注册表对所有任务进行装饰decorate例如把任务函数绑定到共享的配置对象上。从源码层面看registry是 Gulp 实例上被显式绑定的方法之一。在 index.js 中Gulp继承自Undertakerutil.inherits(Gulp, Undertaker)并在构造函数中执行this.registry this.registry.bind(this)随后通过 index.mjs 以 ES Module 形式导出export const registry gulp.registry。因此无论你使用 CommonJS 的const { registry } require(gulp)还是 ESM 的import { registry } from gulp都能拿到同一个绑定方法。测试文件 test/index.test.js 也专门断言了gulp实例拥有registry属性。注意只有通过task()注册的任务才会被提供给自定义注册表。直接传给series()或parallel()的函数不会被转交给注册表——如果需要自定义注册表的行为请用字符串引用组合任务详见 registry() API 的说明。注册表必须遵循的结构为了让 Gulp 接受自定义注册表必须遵循特定的格式它必须是一个对象通常是一个类的实例并实现以下四个方法// 以函数构造函数 原型方法形式 function TestRegistry() {} TestRegistry.prototype.init function (gulpInst) {} TestRegistry.prototype.get function (name) {} TestRegistry.prototype.set function (name, fn) {} TestRegistry.prototype.tasks function () {} // 以类class形式 class TestRegistry { init(gulpInst) {} get(name) {} set(name, fn) {} tasks() {} }如果传入registry()的实例缺少这四个方法中的任意一个Gulp 都会抛出错误。根据 registry() API 的 Errors 一节缺失不同方法会得到对应错误信息缺失的方法错误信息getCustom registry must have get function.setCustom registry must have set function.initCustom registry must have init function.tasksCustom registry must have tasks function.从结构上推断这四者分别承担了注册表的完整生命周期职责init在接入时初始化、set接收新任务、get按名解析任务、tasks枚举全部任务。注册传实例而不是构造函数要注册上文示例中的注册表你需要把它的实例传给registry()而不是构造函数本身const { registry } require(gulp); // ... TestRegistry 定义代码 // 正确 registry(new TestRegistry()) // 错误 registry(TestRegistry()) // 会触发错误Custom registries must be instantiated, but it looks like you passed a constructorregistry()的签名很简单registry([registryInstance])。传参时接受一个自定义注册表的实例object注意是实例而不是类不返回任何值不传参时返回当前的注册表实例可用于读取当前状态。另外需要注意一个重要的行为当分配一个新的注册表时当前注册表中的每个任务都会被转移到新注册表当前注册表会被新注册表替换。这意味着你可以依次调用多次registry()把多个自定义注册表按顺序叠加——后注册的注册表会接管前面注册表持有的任务这正是下文共享功能用例中ConfigRegistry能重置既有任务的前提。四个方法详解init(gulpInst)init()方法会在registry()函数的最后被调用。它接收的唯一参数是 gulp 实例你可以用它通过gulpInst.task(taskName, fn)预先定义任务。参数类型说明gulpInstobjectgulp 实例。init是注册表做初始化注册的入口共享任务的注册逻辑通常都放在这里见下文共享任务用例。get(name)get()方法接收一个任务name自定义注册表负责解析并返回对应的任务如果不存在同名任务则返回undefined。参数类型说明namestring要检索的任务名称。当你在series(clean, build)中以字符串引用任务或通过task(build)读取任务时任务系统最终会调用注册表的get()来解析该名称对应的任务函数。set(name, fn)set()方法接收任务name和任务函数fn。当用户通过task()注册任务时任务系统内部会调用set()把任务交给自定义注册表存储。参数类型说明namestring要设置的任务名称。fnfunction要设置的任务函数。set()是任务装饰器的关键挂钩因为所有用户任务都会经过它重写该方法即可在任务入表时对fn进行包装、绑定或改写见下文共享功能用例。tasks()tasks()必须返回一个对象列出注册表中的所有任务键为任务名值为任务函数。任务树tree()以及命令行列出任务时依赖它获取完整任务清单。用例一跨项目共享任务Sharing Tasks要把通用任务共享给所有项目你可以在注册表上暴露init方法——它会在注册时收到 gulp 实例随后你就可以用gulpInst.task(name, fn)注册预定义任务。例如你可能想共享一个clean任务const fs require(fs); const util require(util); const DefaultRegistry require(undertaker-registry); const del require(del); function CommonRegistry(opts){ DefaultRegistry.call(this); opts opts || {}; this.buildDir opts.buildDir || ./build; } util.inherits(CommonRegistry, DefaultRegistry); CommonRegistry.prototype.init function(gulpInst) { const buildDir this.buildDir; const exists fs.existsSync(buildDir); if(exists){ throw new Error(Cannot initialize common tasks. buildDir directory exists.); } gulpInst.task(clean, function(){ return del([buildDir]); }); } module.exports CommonRegistry;这个示例演示了几个要点继承默认注册表CommonRegistry通过DefaultRegistry.call(this)与util.inherits(CommonRegistry, DefaultRegistry)继承undertaker-registry从而复用默认注册表对get/set/tasks的实现只需要自定义init构造函数接收选项opts.buildDir可配置清理目录默认./build并允许缺省在init中做前置校验如果构建目录已存在直接抛错阻止初始化避免误删用 gulp 实例注册共享任务gulpInst.task(clean, fn)注册的clean任务会进入注册表供所有接入该注册表的项目使用。然后在任意项目中使用它const { registry, series, task } require(gulp); const CommonRegistry require(myorg-common-tasks); registry(new CommonRegistry({ buildDir: /dist })); task(build, series(clean, function build(cb) { // do things cb(); }));项目里只需两件事用registry(new CommonRegistry(...))接入共享注册表然后用task(build, series(clean, ...))组合任务——series中的字符串clean会经由注册表解析到共享任务。关于task()的更多细节如displayName、description、flags等任务元数据可参考 task() API。用例二共享功能 / 任务装饰器Sharing Functionality通过控制任务如何被加入注册表你可以对它们进行装饰。例如如果你想给所有任务共享一份数据可以用自定义注册表把它们绑定到这份数据上。注意要返回改写后的任务遵循上文对注册表方法的描述const { registry, series, task } require(gulp); const util require(util); const DefaultRegistry require(undertaker-registry); // 在别处定义的任务 const BuildRegistry require(./build.js); const ServeRegistry require(./serve.js); function ConfigRegistry(config){ DefaultRegistry.call(this); this.config config; } util.inherits(ConfigRegistry, DefaultRegistry); ConfigRegistry.prototype.set function set(name, fn) { var bound fn.bind(this.config); // 保留内部属性与任务元数据。 var task Object.assign(bound, fn); // DefaultRegistry 使用 this._tasks 存储任务。 this._tasks[name] task; return task; }; registry(new BuildRegistry()); registry(new ServeRegistry()); // registry 会用 ConfigRegistry.prototype.set 重置注册表中的每个任务 // 使它们全部绑定到 config 对象上。 registry(new ConfigRegistry({ src: ./src, build: ./build, bindTo: 0.0.0.0:8888 })); task(default, series(clean, build, serve, function(cb) { console.log(Server bind to this.bindTo); console.log(Serving this.build); cb(); }));这个用例把本文讲到的机制串联了起来set()是装饰入口重写ConfigRegistry.prototype.set在任务入表前执行fn.bind(this.config)让任务函数体内的this指向共享配置对象Object.assign(bound, fn)保留元数据绑定产生的新函数会丢失原函数的内部属性如displayName、description、flags等任务元数据通过Object.assign拷贝回去确保任务在命令行中的描述和名称信息不丢失this._tasks[name] task手动存储默认注册表用this._tasks作为内部存储重写set后需要自行写入并返回改写后的任务顺序注册的叠加效果由于分配新注册表时当前注册表的每个任务都会被转移到新注册表registry(new ConfigRegistry(...))会把之前BuildRegistry、ServeRegistry中的任务全部接管并用ConfigRegistry.prototype.set重新处理后绑定到 config 上——这就是注释所说明的registry会用ConfigRegistry.prototype.set重置注册表中的每个任务任务内直接访问配置series(clean, build, serve, ...)中的字符串任务与匿名函数都被绑定到了 config因此this.bindTo、this.build都能取到配置值。从源码理解调用关系回到源码层面梳理整条调用链可以更清晰地理解注册表机制在 Gulp 中的位置入口Gulp 实例在 index.js 中继承Undertaker并绑定registry、task、series、parallel、tree、lastRun等方法其中registry/task等任务系统能力来自undertaker依赖见 package.json 中undertaker: ^2.0.0双模块导出CommonJS 入口 index.js 导出单例instESM 入口 index.mjs 导出registry等具名绑定两种模块系统行为一致方法契约registry()要求实例具备init/get/set/tasks四方法并逐一校验错误信息见 registry() API 的 Errors 一节init在注册流程末尾被调用set由task()内部触发get负责任务解析tasks提供全量清单测试佐证test/index.test.js 断言gulp实例拥有registry属性确认该 API 作为 Gulp 公共接口的一部分存在。官方参考实现与延伸阅读官方仓库提供了三个与自定义注册表直接相关的实现可作为学习与生产参考undertaker-registryGulp 4 的默认注册表也是自定义注册表最常用的基类本文两个用例都继承了它undertaker-common-tasks概念验证性质的自定义注册表预先定义通用任务即共享任务模式的参考undertaker-task-metadata概念验证性质的自定义注册表为每个任务附加元数据即任务装饰器模式的参考。如需进一步深入建议按顺序阅读仓库内的以下资源registry() API 文档完整的签名、参数、返回值与全部错误信息task() API 文档任务如何注册、检索以及任务元数据displayName/description/flags的挂载方式创建任务 与 异步完成理解任务函数签名与异步约定写出能被自定义注册表正确包装的任务。小结自定义注册表是 Gulp 任务系统的扩展点其核心是一份四方法契约init(gulpInst)用于初始化并预注册共享任务set(name, fn)在task()注册任务时被调用也是任务装饰的唯一挂钩get(name)负责按名解析任务tasks()返回全量任务清单。注册时务必传入实例new Registry()而非构造函数并牢记新注册表会接管当前注册表中的所有任务这一转移语义。基于这套机制你既可以实现跨项目复用的共享任务库也可以实现把任务统一绑定到配置对象、附加元数据等增强功能——这正是 Gulp 任务系统保持开放与可扩展的关键所在。【免费下载链接】gulpA toolkit to automate enhance your workflow项目地址: https://gitcode.com/gh_mirrors/gu/gulp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考