深入 Solidarity 源码Gluegun Listr 如何编排跨平台环境检查任务【免费下载链接】solidaritySolidarity is an environment checker for project dependencies across multiple machines.项目地址: https://gitcode.com/gh_mirrors/so/solidaritySolidarity 是一款跨平台的环境检查工具用于解决“同一份代码在 A 机器上能跑、在 B 机器上却报错”的经典问题。它的核心思路是在项目里放一个.solidarity文件声明环境规则然后由命令行工具把规则逐条“跑”在你的机器上验证。这篇文章带你深入它的源码看看 Gluegun 与 Listr 这两个框架是如何分工协作把一次看似简单的环境检查编排得如此优雅的。一、为什么用 Gluegun 搭脚手架Gluegun 是一个面向开发者的 CLI 框架它帮 Solidarity 省去了解析参数、加载命令、管理插件的大量样板代码。入口逻辑非常精炼全部集中在 src/index.tsconst cli build() .brand(solidarity) .src(__dirname) .plugins(./node_modules, { matching: solidarity-*, hidden: true }) .plugins(/usr/local/lib/node_modules, { matching: solidarity-*, hidden: true }) // ... Yarn、Windows 等安装路径这里有三个值得新手学习的设计点约定优于配置.src(__dirname)表示 Gluegun 会自动把src/commands/目录下的每个文件映射为一条命令比如solidarity.ts对应主检查命令snapshot.ts对应快照命令onboard.ts对应交互式引导命令。多路径插件发现通过多次调用.plugins()工具会同时扫描本地node_modules、macOS 全局目录、Yarn 全局目录和 Windows 的appdata目录凡是命名符合solidarity-*的包都会被自动装载——这就是它能跨 macOS / Linux / Windows 无缝工作的关键之一。上下文注入每个命令执行时都会拿到一个共享的context对象。Solidarity 通过扩展文件 src/extensions/solidarity-extension.ts 往 context 上挂自定义能力context.solidarity solidarity // 所有检查函数 context.addPlugin addPlugin // 插件注册入口 context.envinfo helpers // 系统信息采集插件比如社区提供的solidarity-react-native通过context.addPlugin()把自己的技术栈检查能力注入进来Solidarity 主程序因此可以“无代码改动”地支持任意新技术。二、Listr两层任务树的编排核心命令的执行逻辑在 src/commands/solidarity.ts。它没有把规则一条条串行写死而是构建了一棵两层嵌套的 Listr 任务树// 外层每个 requirement 是一个任务 const checks new Listr( await toPairs(solidaritySettings.requirements).map(requirement ({ title: requirement[0], task: async () checkRequirement(requirement, context, Boolean(parameters.options.fix)), })), listrSettings // { concurrent: true, exitOnError: false, ... } ) await checks.run()外层 Listr 负责“需求组”级别的编排配置里有两处点睛之笔配置项作用concurrent: true各需求组并行执行速度更快exitOnError: false单项失败不中断最后统一判定退出码内层则发生在 src/extensions/functions/checkRequirement.ts每个需求组下的多条规则binary、env、dir、file、shell、custom通过一个switch分发到对应的检查函数再被打包成子任务塞进第二个 Listr// 按规则类型分发到具体 checker switch (rule.rule) { case cli: task taskWithFix(checkCLI, rule, context); break case env: task taskWithFix(checkENV, rule, context); break case directory: task taskWithFix(checkDir, rule, context); break case file: task taskWithFix(checkFile, rule, context); break case shell: task taskWithFix(checkShell, rule, context); break case custom: /* 调用插件的 check 函数 */ }这个两层结构带来的好处非常直观Listr 的渲染器会自动把每个任务打印成带 ✅/❌ 的进度列表用户一眼就能看到“哪个检查通过了、哪条规则失败”而开发者则用递归的“任务组套任务”模式复用同一套进度 UI。失败自动修复taskWithFix 的高明之处checkRequirement.ts里还藏着一个精巧的包装器const taskWithFix (checker, rule, context) async () { try { return await checker(rule, context) } catch (error) { if (rule.fix) { await context.system.run(rule.fix) // 执行 .solidarity 中声明的修复命令 return checker(rule, context) // 重试一次 } throw new Error(No fix script provided in .solidarity file) } }以 CLI 检查为例src/extensions/functions/checkCLI.ts它会先用binaryExists定位可执行文件再用 semver 比对版本不满足则抛出带可读信息的错误。当配合--fix参数时失败后会自动执行项目声明的修复脚本并重试——把“检查”和“修复”缝合成一个闭环这是任务编排框架才能轻松做到的事情。三、报告模式同一批规则另一种消费方式除了逐项打勾的“检查模式”Solidarity 还有面向 Issue 反馈的“报告模式”。src/commands/report.ts复用同一套规则加载逻辑但换掉了执行引擎用Promise.all并行跑完所有规则把结果收集成表格再由 src/extensions/functions/solidarityReport.ts 借助 envinfo 采集系统信息最终由printResults输出为可直接粘贴到 Issue 里的 Markdown 表格同一份.solidarity规则在 Listr 下是“本地体检”在 Report 下是“环境快照”——规则的声明与执行完全解耦这正是任务编排架构的红利。四、规则从哪来.solidarity 文件与插件生态一切检查的“剧本”来自项目根目录的.solidarity或.solidarity.json文件。加载逻辑在 src/extensions/functions/getSolidaritySettings.ts它按优先级依次查找--solidarity-file显式指定的文件--module指定的 npm 模块--stack指定的在线检查集当前目录的.solidarity/.solidarity.json如果都没找到会给出“先运行solidarity onboard”的友好提示。文件的结构遵循仓库根目录的 solidaritySchema.json 校验核心就是requirements下的一组规则{ requirements: { NodeJS: [{ rule: cli, binary: node, semver: 7.6.0 }], Yarn: [{ rule: cli, binary: yarn }] } }规则既可以手写也可以由插件生成solidarity snapshot命令src/commands/snapshot.ts会列出所有已安装的插件按模板生成规则文件再用updateVersions把当前机器上的真实版本号回填进去。交互式创建规则的流程则位于 src/extensions/functions/onboard/index.ts按“打印向导 → 添加规则 → 追加确认 → 保存”的小步骤流水线推进同样是 Gluegun prompt 组合函数的风格。五、小结这套编排架构学到了什么Gluegun 负责“框架层”命令路由、插件发现、上下文注入让 Solidarity 的主入口只有 20 来行代码 Listr 负责“执行层”两层任务树 并发执行 失败聚合把进度展示和错误处理统一收口 规则即数据.solidarity文件是纯声明式配置检查器、报告器、修复器都以同一份数据为输入 插件即能力solidarity-*命名的包自动被多平台路径扫描装载扩展技术栈无需改主程序。对新手来说Solidarity 是一个极佳的“CLI 工程化”学习样本想理解一个命令行工具如何组织命令、插件与并发任务按src/index.ts → src/commands/ → src/extensions/functions/这条路径读源码一天就能摸清脉络。【免费下载链接】solidaritySolidarity is an environment checker for project dependencies across multiple machines.项目地址: https://gitcode.com/gh_mirrors/so/solidarity创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考