Backstage CLI 维护模块实战指南使用 repo fix 与 repo list-deprecations 管理仓库健康【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage导读本文聚焦 Backstage 开源仓库中的 CLI 维护模块backstage/cli-module-maintenance深入讲解其提供的两个核心命令——repo fix自动修复全仓包配置问题与repo list-deprecations全仓废弃 API 使用审计。你将掌握这两个命令的完整参数、工作原理、在 CI 中的落地方式以及它们背后的源码实现细节从而在维护多包仓库monorepo时实现配置同步自动化与废弃依赖的迁移规划。维护模块在 Backstage CLI 中的定位Backstage CLI 采用模块化架构由一组相互独立的CLI 模块组成每个模块提供一组相关命令。官方默认发行版backstage/cli-defaults聚合了 13 个默认模块其中Maintenance模块对应的正是backstage/cli-module-maintenance提供repo fix与repo list-deprecations两个命令用于修复常见包问题并在整个项目中追踪废弃 API见 docs/tooling/cli/05-modules.md。模块的发现机制很简单CLI 启动时会扫描项目根目录package.json中所有依赖凡是包自身package.json中backstage.role字段为cli-module的都会被加载。因此你既可以随backstage/cli-defaults一起使用它也可以单独安装该模块以只启用维护相关命令。在源码层面模块的注册入口位于 packages/cli-module-maintenance/src/index.ts它通过createCliModule注册两条命令路径export default createCliModule({ packageJson, init: async reg { reg.addCommand({ path: [repo, fix], description: Automatically fix packages in the project, execute: { loader: () import(./commands/repo/fix) }, }); reg.addCommand({ path: [repo, list-deprecations], description: List deprecations, execute: { loader: () import(./commands/repo/list-deprecations) }, }); }, });命令采用懒加载import()方式加载只有在真正执行时才加载对应实现避免了 CLI 启动时的额外开销。repo fix自动修复全仓包配置命令基本用法repo fix会扫描项目中的全部包并对常见问题如缺失或错误的配置自动应用修复。原文档给出的命令用法如下Usage: backstage-cli repo fix [options] Automatically fix packages in the project在 Backstage 自身的根仓库中根package.json通常注册了fix: backstage-cli repo fix脚本因此可以直接运行yarn fix触发。如果脚本未注册则需完整运行yarn backstage-cli repo fix。两个关键选项--check 与 --publish参考 packages/cli-module-maintenance/cli-report.md 与 fix.ts 的实现repo fix实际支持以下参数选项类型说明--checkBoolean仅检查若存在会被修改的包则打印提示并以退出码 1 失败不实际写入任何文件--publishBoolean启用仅在发布包时才适用的额外修复项见下文-h, --helpBoolean显示帮助信息--check模式非常适合接入 CI它不会改动工作区而是通过printPackageFixHint打印出“不同步、需要修复”的包列表并返回非零退出码让流水线在配置漂移时及时失败。--publish模式则在默认修复项之外追加发布相关的元数据修复。默认修复项exports 与 sideEffectsrepo fix的核心逻辑在 packages/cli-module-maintenance/src/commands/repo/fix.ts 中。命令先通过PackageGraph.listTargetPackages()读取全部目标包然后依次执行一组 fixerfixers数组最后在--check模式下只报告、否则通过writeFixedPackages以 2 空格缩进写回被修改的package.json。默认无论是否--publish都会执行两个修复器fixPackageExports—— 修正 exports 字段若exports是字符串会重写为对象形式并补上./package.json入口根据 exports 中指向脚本文件.js、.jsx、.ts、.tsx、.json的路径自动生成或更新typesVersions字段清理publishConfig中已不再需要的main、module、browser、types等遗留字段。fixSideEffects—— 为前端包标记无副作用仅对web与common平台的角色生效node 平台角色跳过跳过纯 bundle 输出的包若包尚未声明sideEffects会在scripts字段上方插入sideEffects: false。根据 v1.18.0 的发布说明将非打包前端包标记为无副作用可以显著减小 Webpack 打包体积见 docs/releases/v1.18.0-changelog.md。发布模式下的修复项--publish当传入--publish时fixers 数组会追加以下四个修复器createRepositoryFieldFixer以根package.json的repository字段为基准为每个子包补齐或修正repository.directory即该包相对仓库根目录的路径。若子包已存在 type/url 与根不一致的repository字段则保持原样、不去覆盖。该检查自 v1.23.0 起加入见 docs/releases/v1.23.0-changelog.md。fixPluginId若包的backstage.role属于插件/模块/库角色但缺少backstage.pluginId则根据包名规则猜测插件 ID 并写入。猜测失败时会抛出明确错误提示手动设置backstage.pluginId或考虑改用web-library/node-library角色。fixPluginPackages为带pluginId的包生成或更新backstage.pluginPackages/backstage.pluginPackage字段。模块角色*-plugin-module会先在仓库内寻找同pluginId的对应插件包找不到则回退到internal/cli提供的已知插件包名表普通插件/库角色则汇总仓库内所有同pluginId且角色属于插件库集合的包名排序后写入pluginPackages。fixPeerModules校验backstage.peerModules字段的合法性——仅允许出现在backend-plugin/frontend-plugin角色上必须是包名字符串数组否则抛出带包路径的详细错误。这些发布元数据与 beps/0009-plugin-metadata 中描述的pluginId/pluginPackages生成机制完全对应该 BEP 明确指出这些字段由backstage-cli repo fix命令基于工作区中存在的包及其backstage.pluginId、backstage.role自动生成与更新。实际运行示例# 直接修复仓库中所有可自动修复的包 yarn backstage-cli repo fix # 仅检查若有包不同步则以非零退出码失败适合 CI yarn backstage-cli repo fix --check # 启用发布相关修复repository / pluginId / pluginPackages / peerModules yarn backstage-cli repo fix --publishrepo list-deprecations全仓废弃 API 审计命令基本用法repo list-deprecations用于列出项目中所有包存在的废弃 API 使用情况输出可用于跟踪废弃 API 的引用并规划迁移工作。原文档给出的用法如下Usage: backstage-cli repo list-deprecations [options] List deprecations该命令自 v1.1.0 起以实验性功能引入会扫描整个项目对废弃 API 的使用见 docs/releases/v1.1.0-changelog.md。参数与退出码选项类型说明--jsonBoolean以 JSON 格式输出结果默认输出人类可读文本-h, --helpBoolean显示帮助信息默认输出格式为路径:行号:列号 - 废弃信息一旦发现任何废弃使用命令会以退出码 1 结束因此可以直接作为 CI 的质量门禁。底层实现ESLint 驱动从 packages/cli-module-maintenance/src/commands/repo/list-deprecations.ts 可以看到该命令的实现非常精巧——它直接复用了 TypeScript ESLint 的废弃检测能力const eslint new ESLint({ cwd: targetPaths.dir, overrideConfig: { plugins: [typescript-eslint], rules: { typescript-eslint/no-deprecated: error, }, parserOptions: { project: [targetPaths.resolveRoot(tsconfig.json)], }, }, extensions: [jsx, ts, tsx, mjs, cjs], });实现要点通过PackageGraph.listTargetPackages()遍历仓库中所有目标包对每个包目录调用eslint.lintFiles(pkg.dir)并只收集typescript-eslint/no-deprecated规则产生的消息将命中项整理为{ path, message, line, column }结构路径统一转换为相对仓库根目录的形式输出时区分--jsonJSON.stringify(deprecations, null, 2)与文本两种格式若存在废弃使用则process.exit(1)。单元测试 list-deprecations.test.ts 验证了完整行为它在测试源码中放置一个带deprecated注释的函数并调用它随后断言命令能输出包含path与message的 JSON 结果并调用process.exit(1)。这从测试层面印证了“发现废弃即失败”的 CI 语义。在 CI 中落地Backstage 官方文档在 docs/getting-started/ci.md 中将yarn backstage-cli repo list-deprecations列为推荐的 CI 检查项之一用于确保合入代码不会引入新的废弃 API 使用。由于该命令在发现问题时返回非零退出码可直接编排进任何 CI 脚本- script: yarn backstage-cli repo list-deprecations实战组合建议针对一个正在演进的多包 Backstage 仓库可以形成如下维护流程定期同步配置运行yarn backstage-cli repo fix或先跑--check预览差异将 exports、typesVersions、sideEffects 等字段对齐到最新规范发布前校验元数据对需要发布的包执行yarn backstage-cli repo fix --publish --check确保repository.directory、pluginId、pluginPackages、peerModules等发布元数据正确持续跟踪废弃 API在 CI 中加入yarn backstage-cli repo list-deprecations将废弃使用拦截在合入之前本地开发时可用--json输出方便脚本化处理或接入代码扫描面板配合迁移工具维护模块与 Migrate 模块versions:bump、migrate package-*等协同使用先掌握废弃现状再按模块分批迁移最后用repo fix收敛配置差异。小结维护模块以极低的接入成本提供了仓库级配置修复与废弃审计能力repo fix用一组声明式的修复器exports、sideEffects、repository、pluginId、pluginPackages、peerModules自动收敛多包配置--check与--publish让它可以安全地嵌入 CI 与发布流程repo list-deprecations则借助 TypeScript ESLint 的no-deprecated规则实现全仓废弃 API 扫描以可解析的文本或 JSON 输出辅助迁移规划。二者相结合构成了 Backstage 仓库日常维护与升级准备的基础工具链。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考