Vue CLI Generator API 完全指南深入理解插件生成器的 18 个核心方法【免费下载链接】vue-cli️ webpack-based tooling for Vue.js Development项目地址: https://gitcode.com/gh_mirrors/vu/vue-cli本篇指南以 Vue CLI 官方文档 Generator API英文版 及其俄文版为骨架结合vue/cli仓库中 GeneratorAPI.js 的实现源码、Generator.js 的调度机制以及 Generator.spec.js 测试用例系统讲解 Generator API 的每个方法。读完本文你将能独立编写插件 generator、理解 Vue CLI 项目脚手架生成的底层机制并学会利用版本断言、依赖合并、配置抽取、模板渲染、代码注入等能力构建健壮的生成器。什么是 Generator API在 Vue CLI 的插件体系中每个插件都可以包含一个generator/index.js或generator.js文件它导出一个函数该函数接收一个api参数——这就是Generator API实例。在 Generator.js 的initPlugins方法中框架会为每个插件创建独立的 API 实例并依次执行// packages/vue/cli/lib/Generator.js const api new GeneratorAPI(id, this, options, rootOptions) await apply(api, options, rootOptions, invoking)从 GeneratorAPI.js 的构造函数可以看到每个 API 实例携带四类关键信息id所属插件的标识符generator当前正在执行的 Generator 实例通过它可以访问虚拟文件树、package.json 等内部状态options传给当前插件的生成选项rootOptions整个 preset 的根选项。同时 API 实例还收集了除vue/cli-service之外所有插件的短名称与链接供模板渲染时使用。Generator API 的全部方法分为几个大类版本查询与断言、路径与插件探测、package.json 扩展、模板渲染、文件后处理与回调、JS 配置生成、代码注入。下面逐一深入。版本查询与断言cliVersion / cliServiceVersion两个版本字符串cliVersion类型string表示调用当前插件的全局vue/cli版本。源码中直接读取../package.json的version字段GeneratorAPI.js。cliServiceVersion类型string表示项目本地的vue/cli-service版本。源码通过loadModule(vue/cli-service/package.json, context)从项目上下文加载该模块的版本号GeneratorAPI.js。需要特别说明的是在生成器单元测试环境设置了VUE_CLI_TEST且VUE_CLI_SKIP_WRITE环境变量中由于文件不会真正写盘、vue/cli-service模块不可加载此时cliServiceVersion会回退为cliVersion。这一点在编写依赖本地 CLI Service 能力的插件测试时非常重要。assertCliVersion / assertCliServiceVersion声明版本要求这两个方法接收一个参数range类型为integer | string即vue/cli或vue/cli-service必须满足的 semver 范围若传入整数如4源码会自动将其转换为^4.0.0-0GeneratorAPI.js并校验必须是整数否则抛出Expected string or integer value.若传入字符串则直接作为 semver 范围校验通过semver.satisfies(..., { includePrerelease: true })时什么都不做不满足则抛出明确错误例如Require global vue/cli ^4.0.0, but was invoked by 3.12.1.Require vue/cli-service ^4.0.0, but was loaded with 3.12.1.官方文档特别提示大多数情况下推荐使用package.json中的peerDependencies字段来声明插件与 CLI 版本的依赖关系而不是在 generator 中硬编码断言。assertCliVersion适用于需要在生成时依据 CLI 能力分支处理、或为旧版本 CLI 提供降级路径的场景。真实案例见 cli-plugin-eslint/generator/index.js它用try { api.assertCliVersion(^4.0.0-beta.0) } catch (e) { ... }来检测是否支持新版 hooks 特性不支持时回退到onCreateComplete执行 lint 修复。路径解析与插件探测resolve参数{string} ..._paths一个或多个相对路径或路径片段返回{string}基于当前项目根目录计算的绝对路径。源码实现非常简洁resolve (..._paths) { return path.resolve(this.generator.context, ..._paths) }它常用于检查项目文件是否已存在。例如 cli-plugin-eslint/generator/index.js 中通过api.resolve(.editorconfig)判断用户是否已有.editorconfig决定是追加还是全新渲染模板。hasPlugin参数{string} id插件 id可省略(vue/|vue-|scope/vue)-cli-plugin-前缀{string} version可选 semver 范围返回{boolean}。该方法委托给generator.hasPlugin(id, versionRange)Generator.js。其判定逻辑值得注意同时检查当前插件列表this.plugins与项目依赖中所有可加载 generator 的插件this.allPlugins来自resolveAllPlugins用matchesPluginId做前缀归一化匹配因此api.hasPlugin(babel)可以命中vue/cli-plugin-babel若提供了版本范围则用semver.satisfies(pm.getInstalledVersion(id), versionRange)校验已安装版本是否满足。该方法是 generator 中最常用的条件分支工具。例如 cli-plugin-router/generator/index.js 用api.hasPlugin(babel) || api.hasPlugin(typescript)决定渲染的模板数据doesCompilecli-service/generator/index.js 则在检测到 typescript 插件时通过api.render(files delete files[jsconfig.json])删除冲突文件。配置抽取addConfigTransform参数{string} keypackage.json 中的配置键{object} options其中options.file是文件描述符用于搜索已存在的配置文件。每个键是一种文件类型可选值为[js, json, yaml, lines]值为文件名列表返回{boolean}源码中无显式返回但类型声明为void见 index.d.ts。官方文档给出的示例{ js: [.eslintrc.js], json: [.eslintrc.json, .eslintrc] }默认情况下每种类型列表中的第一个文件名用于创建配置文件。该方法的作用是当插件通过extendPackage向package.json写入形如eslintConfig、babel、postcss这类工具配置字段时定义它们应被抽取extract到哪种独立配置文件。其底层实现GeneratorAPI.js有两个关键细节保留键保护Generator内部预置了reservedConfigTransforms当前包含vue映射到vue.config.js向保留键注册会被拒绝并打印Reserved config transform vue警告注册的 transform 被存入generator.configTransforms在Generator.generate的extractConfigFiles阶段Generator.js与默认 transform覆盖babel、postcss、eslintConfig、jest、browserslist、lint-staged合并使用。ConfigTransform的转换逻辑在 ConfigTransform.js 中若checkExisting为真先在虚拟文件树中按文件描述符顺序查找已存在的文件findFile找到则先读取其现有内容再合并写入找不到或未开启时使用默认文件名。转换实际由 configTransforms.js 按类型js/json/yaml/lines完成。测试用例 Generator.spec.js 验证了两种形态单一 json 描述符fooConfig→foo.config.json和多类型描述符bazConfig注册js: [.bazrc.js]、json: [.bazrc, baz.config.json]默认落到.bazrc.js。扩展 package.jsonextendPackage参数{object | () object} fields要合并的字段可选第二个参数{object} options用法扩展项目的package.json。嵌套字段会深度合并除非传入{ merge: false }同时解决插件之间的依赖冲突工具配置字段可能在文件写盘前被抽取到独立文件。这是 generator 中最常用的方法。源码 GeneratorAPI.js 揭示了丰富的细节fields可以是函数接收当前pkg对象返回要合并的对象便于做条件判断依赖字段特殊处理dependencies与devDependencies总是走mergeDeps专门合并逻辑mergeDeps.js不受merge: false影响options支持四个开关prune默认false合并后删除值为null/undefined的字段merge默认true是否深度合并嵌套字段数组会按Array.from(new Set([...a, ...b]))去重合并warnIncompatibleVersions默认true两个插件注入的同一依赖版本范围不兼容时输出警告forceOverwrite默认false强制使用第一个参数中的依赖版本而非尝试取较新版本。兼容性4.0.0 到 4.1.2 时代第二个参数曾是一个布尔forceNewVersion标志源码做了向后兼容处理。mergeDeps的版本冲突解决策略是对同一依赖若已有版本与注入版本相同则跳过若注入范围合法semver、GitHub 仓库形式或 URI 形式且能推断出更新的兼容范围则使用新范围否则保留已有版本并可能打印冲突警告。这使得多个插件各自声明vue-router、core-js等依赖时不会互相覆盖。真实案例// packages/vue/cli-plugin-router/generator/index.js api.extendPackage({ dependencies: { vue-router: ^3.5.1 } })// packages/vue/cli-service/generator/index.js api.extendPackage({ scripts: { serve: vue-cli-service serve, build: vue-cli-service build }, browserslist: [ 1%, last 2 versions, not dead ] })注意 cli-plugin-babel/generator.js 中的技巧它先用delete api.generator.files[babel.config.js]删除虚拟文件树中可能存在的旧配置再extendPackage写入babel.presets从而保证整个配置被覆盖、避免冲突。模板渲染render 的三种形态参数{string | object | FileMiddleware} source可以是相对路径指向一个模板目录对象哈希{ sourceTemplate: targetFile }自定义文件 middleware 函数{object} [additionalData]模板可用的附加数据{object} [ejsOptions]ejs 的渲染选项用法将模板文件渲染进虚拟文件树对象。render的三种形态在源码 GeneratorAPI.js 中对应三条分支目录形态api.render(./template, data)。源码用extractCallDir()通过错误堆栈推断调用者文件所在目录把相对路径解析为绝对路径再用globby([**/*], { cwd: source, dot: true })递归收集所有文件。这里有一个重要约定npm 发布时会忽略点文件因此模板中的点文件要用下划线前缀代替——渲染时会把_gitignore还原为.gitignore__双下划线前缀则剥掉一个下划线。每个文件经过renderFile处理二进制文件直接返回 Buffer 原样拷贝文本文件先经yaml-front-matter解析 front matter支持when条件渲染、extend模板继承与replace正则替换最终用 ejs 渲染。空白内容文件会被跳过。对象映射形态api.render({ main.js: path.join(templateDir, entry.js) })将指定模板文件渲染到指定目标路径。测试用例 Generator.spec.js 中正是用这种形态渲染入口文件后再注入根选项。middleware 函数形态api.render(files { ... })直接接收虚拟文件树对象进行任意修改。例如 cli-service/generator/index.js 用api.render((files) delete files[jsconfig.json])删除文件cli-plugin-eslint/generator/index.js 用它向已有.editorconfig追加内容。模板可访问的数据由_resolveDataGeneratorAPI.js提供options当前插件选项、rootOptions根选项、plugins除 cli-service 外所有插件的短名与链接列表再加上additionalData。文件后处理与生命周期回调postProcessFiles参数{FileMiddleware} cb用法压入一个文件 middleware它将在所有普通文件 middleware 执行完毕之后运行。在Generator.resolveFilesGenerator.js中执行顺序是先依次执行全部fileMiddlewaresrender 注册的→ 路径归一化 → import 与根选项注入 → 最后执行postProcessFilesCbs。因此postProcessFiles适合做全局性的收尾修改例如 cli-plugin-typescript/generator/convert.js 用它统一改写文件。onCreateComplete参数{function} cb用法压入一个回调在文件写入磁盘之后调用。源码中onCreateComplete与afterInvoke等价GeneratorAPI.js都推入generator.afterInvokeCbs。典型用途是在生成完成后执行需要真实文件系统的操作比如 cli-plugin-eslint/generator/index.js 在生成完成后自动运行 lint 修复。测试 Generator.spec.js 验证了api.onCreateComplete(fn)注册的回调会按预期触发。补充说明与afterInvoke相对的还有afterAnyInvoke非文档主述但源码中存在它收集任意插件被调用时的钩子例如 eslint 插件的module.exports.hooks中使用api.afterAnyInvoke在生成流程末尾执行 lint。exitLog参数{*} msg生成完成后要打印的内容{(log|info|done|warn|error)} [typelog]消息类型默认log用法添加一条生成器退出时打印的消息排在其它标准消息之后。实现上推入generator.exitLogsGeneratorAPI.js由Generator.printExitLogsGenerator.js按注册顺序映射到logger.log/info/done/warn/error输出未知类型会打印Invalid api.exitLog type错误。真实案例cli-plugin-eslint/migrator/index.js 输出ESLint upgraded from vX. to v7cli-plugin-babel/migrator/index.js 提示 core-js 从 v2 升级到 v3。JS 配置生成genJSConfig 与 makeJSOnlyValuegenJSConfig参数{any} value用法便捷地从 JSON 生成 JS 配置文件内容。源码实现GeneratorAPI.jsgenJSConfig (value) { return module.exports ${stringifyJS(value, null, 2)} }底层stringifyJSstringifyJS.js使用javascript-stringify以 2 空格缩进序列化对象。makeJSOnlyValue参数{any} str字符串形式的 JS 表达式用法把字符串表达式转成 .js 配置文件中可执行的 JS。这是genJSConfig系列的精髓。实现是返回一个带有__expression标记的空函数makeJSOnlyValue (str) { const fn () {} fn.__expression str return fn }stringifyJS在序列化时检测到__expression标记会直接输出原始表达式而不是函数本身。这样就能在 JSON 风格的对象里嵌入活的 JS 代码。最典型的应用在 cli-plugin-eslint/eslintOptions.jsrules: { no-console: makeJSOnlyValue(process.env.NODE_ENV production ? warn : off), no-debugger: makeJSOnlyValue(process.env.NODE_ENV production ? warn : off) }当eslintConfig被抽取为.eslintrc.js时这两条规则会变成真实的条件表达式而非字符串使规则在不同环境动态生效。类型定义中它返回__expressionFn见 index.d.ts。代码注入injectImports 与 injectRootOptionsinjectImports参数{string} file目标文件{string | [string]} imports导入语句字符串或数组用法向文件添加 import 语句。实现将导入语句收集到generator.imports[file]的Set中自动去重GeneratorAPI.js在resolveFiles阶段通过vue-codemod的injectImportscodemod 注入文件Generator.js。典型用法// packages/vue/cli-plugin-router/generator/index.js api.injectImports(api.entryFile, import router from ./router)injectRootOptions参数{string} file目标文件{string | [string]} options选项字符串或数组用法向根 Vue 实例通过new Vue检测添加选项。同样通过Set收集并在解析阶段用injectOptionscodemod 注入到new Vue({ ... })的对象中。经典示例// packages/vue/cli-plugin-router/generator/index.js (Vue 2 分支) api.injectRootOptions(api.entryFile, router)生成的入口文件会包含new Vue({ router, render: h h(App) })。测试用例Generator.spec.js验证了非标识符表达式如p: p()也能正确注入到根选项对象中。入口文件与调用状态entryFile返回{(src/main.ts|src/main.js)}用法获取入口文件自动考虑 TypeScript。实现是带缓存的只读 getterGeneratorAPI.jsget entryFile () { if (this._entryFile) return this._entryFile return (this._entryFile fs.existsSync(this.resolve(src/main.ts)) ? src/main.ts : src/main.js) }即项目根下存在src/main.ts就返回它否则返回src/main.js。这让插件无需关心项目是否使用 TypeScript直接对入口文件注入 import 或根选项即可。invoking返回{boolean}用法判断插件是否处于被调用状态即执行vue invoke/vue add向已有项目添加插件而非首次创建项目。实现直接透传this.generator.invoking。典型应用见 cli-plugin-router/generator/index.js仅在api.invoking为真时才对 TypeScript 项目执行额外的文件转换cli-plugin-eslint/generator/index.js 也在 invoking 分支里为已存在的单测插件补充 ESLint 适配。插件 generator 的整体编写范式综合上述 API一个完整的插件 generator 通常遵循以下流程可在 cli-plugin-router/generator/index.js 中看到完整示例条件分支用api.hasPlugin(...)、api.invoking、rootOptions.vueVersion判断项目形态声明依赖与脚本用api.extendPackage(...)合并依赖、scripts 与工具配置渲染模板用api.render(./template, data)渲染目录模板必要时用对象映射或 middleware 形态做定制注入代码用api.injectImports/api.injectRootOptions配合api.entryFile修改入口文件收尾处理用api.postProcessFiles做文件后处理api.onCreateComplete在写盘后执行异步任务api.exitLog输出完成提示版本兼容用api.assertCliVersion/api.assertCliServiceVersion声明运行前提。需要说明的是cli-plugin-router/generator/index.js 中还使用了文档未单独列出但源码确实存在的api.transformScript(file, codemod, options)它基于vue-codemod对脚本或.vue文件的 script 部分执行 codemod 转换适合复杂重构场景本文聚焦文档主述的 18 个方法此处仅作延伸提及。总结Generator API 是 Vue CLI 插件体系的生成期核心它把版本感知、依赖合并、配置抽取、模板渲染、代码注入等能力统一封装在一个api对象上。通过 GeneratorAPI.js 源码可以看出所有方法本质上是往Generator的各类队列fileMiddlewares、postProcessFilesCbs、afterInvokeCbs、exitLogs、imports、rootOptions、configTransforms中登记操作最终由Generator.generate()统一编排执行——先初始化插件、抽取配置文件、解析文件树、写入磁盘。理解这一调度模型再对照官方文档中的方法签名与本文涉及的源码路径你就能写出行为可预测、版本兼容、可测试的 Vue CLI 插件 generator。【免费下载链接】vue-cli️ webpack-based tooling for Vue.js Development项目地址: https://gitcode.com/gh_mirrors/vu/vue-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考