企业官网建设流程全解析

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实际支持以下参数：

--check模式非常适合接入 CI：它不会改动工作区，而是通过printPackageFixHint打印出“不同步、需要修复”的包列表并返回非零退出码，让流水线在配置漂移时及时失败。--publish模式则在默认修复项之外追加发布相关的元数据修复。

默认修复项：exports 与 sideEffects

repo fix的核心逻辑在 packages/cli-module-maintenance/src/commands/repo/fix.ts 中。命令先通过PackageGraph.listTargetPackages()读取全部目标包，然后依次执行一组 fixer（fixers数组），最后在--check模式下只报告、否则通过writeFixedPackages以 2 空格缩进写回被修改的package.json。

默认（无论是否--publish）都会执行两个修复器：

1. fixPackageExports—— 修正 exports 字段：

   • 若exports是字符串，会重写为对象形式并补上"./package.json"入口；
   • 根据 exports 中指向脚本文件（.js、.jsx、.ts、.tsx、.json）的路径，自动生成或更新typesVersions字段；
   • 清理publishConfig中已不再需要的main、module、browser、types等遗留字段。

2. 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 --publish

repo 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）。

参数与退出码

默认输出格式为路径:行号:列号 - 废弃信息；一旦发现任何废弃使用，命令会以退出码 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'], });

实现要点：

1. 通过PackageGraph.listTargetPackages()遍历仓库中所有目标包；
2. 对每个包目录调用eslint.lintFiles(pkg.dir)，并只收集@typescript-eslint/no-deprecated规则产生的消息；
3. 将命中项整理为{ path, message, line, column }结构，路径统一转换为相对仓库根目录的形式；
4. 输出时区分--json（JSON.stringify(deprecations, null, 2)）与文本两种格式；
5. 若存在废弃使用则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 仓库，可以形成如下维护流程：

1. 定期同步配置：运行yarn backstage-cli repo fix（或先跑--check预览差异），将 exports、typesVersions、sideEffects 等字段对齐到最新规范；
2. 发布前校验元数据：对需要发布的包执行yarn backstage-cli repo fix --publish --check，确保repository.directory、pluginId、pluginPackages、peerModules等发布元数据正确；
3. 持续跟踪废弃 API：在 CI 中加入yarn backstage-cli repo list-deprecations，将废弃使用拦截在合入之前；本地开发时可用--json输出，方便脚本化处理或接入代码扫描面板；
4. 配合迁移工具：维护模块与 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