Backstage CLI 模块info命令实战用backstage-cli-module-info输出环境与依赖诊断报告【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage导读backstage/cli-module-info是 Backstage CLI 的一个官方 CLI 模块为命令行工具提供info命令用于输出当前开发环境的系统信息与 Backstage 依赖清单是调试环境和填写 Bug 报告时的第一手诊断工具。读完本文你将掌握info命令的全部用法含--format、--include两个核心参数、理解其文本与 JSON 两种输出结构的含义并深入了解它背后的 yarn.lock 解析与工作区依赖分类原理。一、模块定位Backstage CLI 模块体系中的诊断利器Backstage CLIbackstage/cli自 0.1.0 版本起引入了CLI 模块cli-module机制每个模块是一组可以被backstage/cli自动发现、也可独立执行的命令集合。backstage/cli-module-info就是其中的一员职责单一而明确——提供info命令Show helpful information for debugging and reporting bugs显示用于调试和报告 Bug 的有用信息。该模块在仓库中的catalog-info.yaml注册为backstage-cli-module类型的组件生命周期标记为experimental归属于tooling-maintainers。它依赖backstage/cli-common、backstage/cli-nodeCLI 模块运行时与锁文件解析能力、cleye命令行参数解析、fs-extra文件系统增强与minimatchglob 模式匹配等库具体依赖清单见 package.json。二、CLI 报告速览命令与全部参数仓库内的 cli-report.md 是一份由yarn build:api-reports自动生成的 CLI 使用报告它完整记录了该模块可执行命令的用法。报告内容如下backstage-cli-module-infoUsage: backstage/cli-module-info [flags...] Options: -V, --version -h, --help Commands: help info模块顶层提供两个全局选项-V/--version输出模块版本与-h/--help帮助信息并暴露两个子命令help与info。从实现看该模块通过createCliModule注册命令入口文件 src/index.ts 中将info命令的path声明为[info]执行体采用惰性加载execute.loader动态 import 命令实现避免未使用命令拖慢启动。backstage-cli-module-info infoUsage: backstage/cli-module-info info [flags...] Options: --format string --include string -h, --helpinfo子命令支持两个参数二者的类型与含义在 src/commands/info.ts 中有完整定义参数类型默认值含义--formatstringtext输出格式支持text与json两种取值--includestring无额外纳入报告的第三方包 glob 匹配模式例如spotify/backstage*可多次指定三、info命令的标准输出五个系统字段默认--format text执行info命令时首先打印一组系统与环境信息对应 src/commands/info.ts 的 console 输出逻辑OS: Darwin 23.6.0 - darwin/arm64 node: v20.16.0 yarn: 4.5.1 cli: 0.33.0 (installed) info module: 0.1.4 backstage: 1.39.0各字段含义如下OS由 Node.js 内置模块node:os拼装而成格式为${type} ${release} - ${platform}/${arch}例如Darwin 23.6.0 - darwin/arm64一次性给出操作系统类型、内核版本与 CPU 架构。node当前 Node.js 运行时版本取自process.version。yarn通过runOutput([yarn, --version])实际执行yarn --version获得因此反映的是环境中真实的包管理器版本。clibackstage/cli的版本号通过解析node_modules/backstage/cli/package.json得到由于模块可独立运行CLI 未必已安装此时该字段不显示。括号内的local/installed用于区分当前是在 Backstage 源码仓库内本地开发还是作为已安装依赖运行。info module当前backstage/cli-module-info模块自身版本号取自 package.json 的version字段。backstageBackstage 版本号读取项目根目录backstage.json中的version字段若文件缺失返回N/A若格式非法会在文本模式下输出警告The backstage.json file is not in the expected format见 src/commands/info.ts。四、依赖报告Dependencies 与 Local 两个区段在系统信息之后info命令输出项目中的 Backstage 相关依赖清单。它基于项目根目录的yarn.lock文件通过backstage/cli-node的Lockfile.load加载见 src/commands/info.ts把所有包名分成三类backstage/*命名空间下的包一律纳入报告匹配--includeglob 模式的包按minimatch规则匹配用于把第三方生态包如spotify/backstage*、janus-idp/*也收进报告package.json 中带backstage字段的包其余包若声明了backstage字段说明其是 Backstage 生态组件同样纳入报告。随后上述包再按是否属于当前工作区workspace拆分为两个区段输出Dependencies: backstage/catalog-client 1.9.0 backstage/catalog-model 1.7.3 backstage/cli 0.33.0 ... (no installed Backstage packages found) # 空时的占位提示 Local: backstage/app-defaults 1.5.13 backstage/backend-app-api 1.20.0 ...Dependencies安装自 npm registry 的包版本号来自 yarn.lock 中锁定的实际条目同一包可能列出多个解析版本以逗号分隔。列宽按最长包名自动对齐便于人眼阅读。Local当前仓库/工作区内的本地包版本取自PackageGraph.listTargetPackages()遍历工作区得到的 package.jsonversion字段。值得注意的是包名是否进入 Local 区段是通过workspacePackages集合判断的见 src/commands/info.ts因此该命令既能在已安装依赖的独立 Backstage 应用中使用也能在 monorepo 源码仓库中正确区分本地与远端版本。五、机器可读输出--format json的结构需要把诊断信息接入 CI、Issue 模板自动填充或上报工具时使用--format jsonbackstage-cli-module-info info --format jsonJSON 输出对应 src/commands/info.ts 的构造逻辑包含三个顶层字段{ system: { os: Linux 6.8.0 - linux/x64, node: v20.16.0, yarn: 4.5.1, cli: { version: 0.33.0, local: false }, infoModuleVersion: 0.1.4, backstage: 1.39.0 }, dependencies: { backstage/catalog-client: [{ version: 1.9.0 }], backstage/catalog-model: [{ version: 1.7.3 }, { version: 1.6.1 }] }, local: { backstage/app-defaults: [{ version: 1.5.13 }] } }字段语义system与文本输出前五段一一对应的系统信息cli仅在 CLI 可解析时出现infoModuleVersion对应文本中的 info modulebackstage对应backstage.json中的版本。dependencies已安装依赖值为版本对象数组——当 yarn.lock 中同一包名存在多个解析版本典型于依赖升级期时数组会有多项。local工作区本地包版本取工作区 package.json 声明版本。选择 json 格式时即使backstage.json解析失败也不会打印警告文本避免污染 stdout 的机器可读性。六、源码级原理一次info执行的完整调用链从 src/commands/info.ts 的实现可以还原info命令的完整执行链路参数解析cleye的cli()解析--include字符串数组与--format默认text见 L55-L77环境探测并行获取 yarn 版本、判断是否运行在本地源码目录通过findOwnPaths(__dirname).resolve(./src)是否存在、读取backstage.json、解析backstage/cli版本组装systemInfo对象L81-L124锁文件解析Lockfile.load读取yarn.lock得到全部锁定包及各自版本L126-L127依赖分类按第三节所述的三条规则把包划入installedDeps/localDeps两个集合其中工作区判断依赖PackageGraph.listTargetPackages()额外包判断通过minimatch完成 glob 匹配hasBackstageField则尝试读取对应 package.json 的backstage字段L34-L53输出按--format分支输出 JSON 或对齐排版的文本L204-L256。整个执行体被包裹在new Promise(...)中命令注册本身通过createCliModule完成见 packages/cli-node/src/cli-module/createCliModule.ts 的addCommand机制模块的公开 API 在 report.api.md 中仅暴露默认的CliModule对象。七、典型使用场景与安装方式填写 Bug 报告GitHub Issue 中要求提供环境信息时直接粘贴info的文本输出即可完整交代 OS / Node / Yarn / CLI / Backstage 版本与全部依赖版本。排查依赖漂移当 Backstage 升级后出现行为不一致用info对比Dependencies区段的锁定版本与期望版本Local区段则用于确认是否意外混用了本地 workspace 源码。集成生态包诊断通过--include把第三方 Backstage 插件纳入报告backstage-cli-module-info info --include spotify/backstage* --include janus-idp/*自动化上报CI 或诊断脚本中使用--format json解析结构化输出避免文本解析脆弱性。安装上该模块随 Backstage 的cli-module体系通过yarn add --dev backstage/cli-module-info加入项目之后既可作为独立可执行文件backstage-cli-module-info运行也可由backstage/cli自动发现其info命令。按其 CHANGELOG.md 记录0.1.0 版本随 CLI 模块机制首次发布0.1.3 起--help输出会生成包含可用 flag 与位置参数的 usage 行0.1.4 为当前仓库中的版本。八、小结backstage/cli-module-info以极小的包体提供了开发体验价值极高的诊断能力一条info命令聚合了系统环境、CLI 版本与全量依赖信息--format json又使其可以无缝嵌入自动化流程。对任何维护 Backstage 应用或贡献插件的人来说它都是定位环境问题、提交高质量 Bug 报告的第一站工具。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考