Backstage 版本升级完全指南：使用 backstage-cli 与 Yarn 插件保持你的 Developer Portal 更新-酒店常州论坛

Backstage 版本升级完全指南：使用 backstage-cli 与 Yarn 插件保持你的 Developer Portal 更新

【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage

本篇技术指南聚焦于如何将 Backstage 应用（Backstage App）持续升级到最新版本，覆盖backstage-cli versions:bump命令的完整用法、@backstage/create-app模板变更的跟踪方法、Backstage Yarn 插件对依赖版本的统一管理，以及企业网络环境下的代理配置与数据库迁移回滚方案。读完本文后，你将掌握一套可落地、可重复的 Backstage 升级流程，能够从容处理依赖冲突、模板漂移与降级回滚等典型场景。

Summary：Backstage 更像一个库，而不是一个应用

Backstage 始终在持续演进，因此与应用保持同步是个好习惯。理解这一点需要先明确一个关键认知：Backstage 更像是一个库（library），而不是一个应用或服务。类似于create-react-app，@backstage/create-app工具为你提供了一个"起点"，而这个起点是注定要被持续演进的——你基于它构建出来的应用，本质上是一份长期维护、不断升级的代码资产。

因此，"保持更新"不是一个一次性动作，而是一条需要纳入日常研发流程的长期实践。下文将从升级命令、模板跟踪、版本管理插件、依赖去重、代理配置与迁移回滚六个维度完整展开。

使用 backstage-cli 升级 Backstage 版本

一条命令批量升级：`versions:bump`

Backstage CLI 提供了一个专门命令来将所有正在使用的@backstage包及其依赖一次性升级到最新版本：

yarn backstage-cli versions:bump

之所以要一次性统一升级所有@backstage包，是因为这些包之间存在相互依赖关系（例如@backstage/core-plugin-api与@backstage/core-components之间、前后端插件 API 之间均存在版本联动）。如果只升级其中一部分，很容易造成包之间的 API 不兼容。

该命令的完整用法与参数（来自 module-migrate 模块文档）：

Usage: backstage-cli versions:bump [options] Options: -h, --help display help for command --pattern <glob> Override glob for matching packages to upgrade --release <version|next|main> Bump to a specific Backstage release line or version (default: "main")

选择发布线：`main`（每月）与`next`（每周）

默认情况下，versions:bump会将@backstage包升级到最新的main发布线，该发布线每月发布一次。如果希望更快地跟进新特性，可以使用--release next选项切换到每周发布的next发布线：

yarn backstage-cli versions:bump --release next

锁定或降级到指定版本

--release选项也支持指定具体版本号，这在以下两种场景中非常有用：

需要将应用固定到某个特定发布版本；
需要降级回之前的版本（例如从1.45.0回退到1.43.0）：

yarn backstage-cli versions:bump --release 1.43.0

:::warning 需要特别注意的是：跨越大版本差距的降级（例如跨越 2～3 个版本）可能会因为 Backstage 的依赖管理方式而导致包版本不匹配或运行错误。此方式最适合小幅调整，请谨慎使用。 :::

扩展升级范围：`--pattern`

如果你还使用了其他非@backstage命名空间的插件，可以通过--pattern选项将升级范围扩展到更多依赖。例如同时升级@backstage/*与@roadiehq/*：

yarn backstage-cli versions:bump --pattern '@{backstage,roadiehq}/*'

源码视角：`versions:bump`到底做了什么

从源码看，该命令的实现位于 packages/cli-module-migrate/src/commands/versions/bump.ts。它揭示了几个有价值的实现细节：

默认匹配范围：当未提供--pattern时，使用默认 glob@backstage/*（见DEFAULT_PATTERN_GLOB常量）；若显式传入*会被直接拒绝并报错，避免误伤全部依赖（bump.ts#L53、L108-L111）。
覆盖四种依赖类型：升级会同时作用于dependencies、devDependencies、peerDependencies和optionalDependencies（DEP_TYPES数组，bump.ts#L46-L51）。
版本解析策略：指定具体版本号时采用"严格"查找（严格按 release manifest 解析）；指定发布线时采用"宽松"查找——main实际是latestdist-tag 的别名，而对next发布线会同时拉取next与main两份 manifest，优先使用 releaseVersion 更新的那一份（bump.ts#L124-L155）。
自动更新backstage.json：当使用默认 pattern（覆盖@backstage/*）时，命令会把目标版本写入仓库根目录的backstage.json；若使用自定义 pattern 则会跳过该步骤并给出提示（bump.ts#L277-L289）。
破坏性变更预警：命令会对比 lockfile 中记录的旧版本与目标新版本，若跨越了 major（或 pre-v1 minor）边界，会打印"⚠️ The following packages may have breaking changes"清单，并附上对应包的 CHANGELOG 路径，提醒你逐一核对（bump.ts#L311-L344）。
隐藏参数：--skipInstall（跳过yarn install）与--skipMigrate（跳过已迁移包的处理）也可用，便于在 CI 等场景中分步执行（bump.ts#L86-L94）。

配套命令：`versions:migrate`

升级之外，migrate 模块还提供versions:migrate命令，用于把已迁移到@backstage-community命名空间的插件依赖自动改名：它会扫描项目内所有包的package.json中带backstage.moved字段的依赖，更新依赖名并（可选地）重写源码中的导入路径，随后自动运行yarn install更新 lockfile。在升级过程中遇到"插件搬家"类问题时可一并使用（详见 module-migrate.md）。

跟踪 create-app 模板变更

@backstage/create-app命令基于一份模板创建你最初的 Backstage 安装结构。这份模板在 Backstage 仓库中会定期更新，但你的本地app与backend包是在create-app那一刻固化下来的，不会自动获得后续的模板更新。

因此，模板的任何改动都会被记录在@backstage/create-app包的 CHANGELOG 中，并附带对应的升级说明。官方建议在升级包时务必翻阅该 changelog，确认是否有适用于你的模板变更。

作为补充手段，Backstage Upgrade Helper（backstage.json中记录了当前安装版本，可直接据此查询两个版本之间的全部差异）能提供两个 Backstage 版本之间所有变更的汇总视图。你可以通过packages/create-app/CHANGELOG.md了解模板变更细节，并在执行versions:bump后留意终端输出——命令完成时会打印类似Upgraded from release X to Y, please review these template changes:的提示并给出 Upgrade Helper 链接（见 bump.ts#L475-L493 的实现逻辑）。

使用 Backstage Yarn 插件管理包版本

为什么需要它

随着 Backstage monorepo 规模增长，手动为每个package.json维护精确的@backstage版本号既繁琐又容易出错。Backstage Yarn 插件解决了这个问题：它根据backstage.json中记录的整体 Backstage 版本，为每个包自动确定合适的版本。这样做的好处是：

无需在 monorepo 的每个package.json中手动维护版本号；
新增@backstage依赖时，不必再费心推算与当前安装的 Backstage 版本匹配的版本号。

环境要求

使用该插件要求yarn 4.1.1 或更高版本。这一要求并非空谈——插件在加载时会用semverUtils.satisfiesWithPrereleases(YarnVersion, '^4.1.1')做严格校验，版本不满足会直接报错并提示升级或卸载插件（见 packages/yarn-plugin/src/index.ts#L42-L48）。

安装方式

在 Backstage monorepo 根目录执行：

yarn plugin import https://versions.backstage.io/v1/tags/main/yarn-plugin

安装后文件系统产生的改动（通常是.yarn/plugins/@yarnpkg/plugin-backstage.cjs以及.yarnrc.yml中的插件声明）应提交到你的代码仓库。

:::tip 最佳实践是在准备执行一次 Backstage 升级时再安装该插件，这样能更方便地确认一切工作正常。 :::

使用方式：`backstage:^`协议

插件安装后，对于当前已发布的@backstage包，你可以在package.json中把版本号替换为字符串"backstage:^"。这告诉 yarn：根据backstage.json中记录的整体 Backstage 版本去解析实际版本。

{ "dependencies": { "@backstage/core-plugin-api": "backstage:^" } }

从源码看，插件在reduceDependencyhook 中识别backstage:协议（常量PROTOCOL = 'backstage:'，见 packages/yarn-plugin/src/constants.ts），校验 selector 必须为^（其他写法会抛错），然后从backstage.json读取当前 Backstage 版本并据此解析出对应的 npm 版本（见 packages/yarn-plugin/src/handlers/reduceDependency.ts）。

:::tipbackstage.json是插件工作的关键，请务必确保该文件包含在你的CI/CD 流水线和/或任何容器构建中。 :::

与`versions:bump`的联动

上文介绍的backstage-cli versions:bump命令会自动检测 yarn 插件是否已安装：一旦检测到，它就会自动把 monorepo 中的依赖迁移为backstage:^写法，并将插件本身同步升级到目标版本对应的 yarn-plugin（bump.ts#L157-L170）。同时注意：

插件被检测到时，升级只对存在于目标 release manifest 中的包使用backstage:^，且peerDependencies不会使用该写法（因为 peer 依赖只支持 npm 与 workspace 协议）（bump.ts#L240-L250）；
如果想从backstage:^迁回显式 npm 版本，可先执行yarn plugin remove @yarnpkg/plugin-backstage移除插件，再重新运行versions:bump。

当前仓库内的工作区示例可参考 workspaces/ui/backstage.json，其内容即为此插件的版本来源：

{ "version": "1.50.0" }

深入理解依赖不匹配问题

Backstage 是一个基于Yarn workspaces组织的 monorepo。这意味着你的app、backend包以及自定义插件都是拥有各自package.json与依赖的独立包。

Yarn 的解析行为决定了两种安装布局：

当某个依赖在不同包之间的版本相同时，该依赖会被提升（hoisted）到 monorepo 根目录的node_modules中共享；
当不同包对同一依赖的版本不一致时，Yarn 会在特定包内部创建各自的node_modules，这可能导致同一个包以多个版本被安装并在同一应用中使用。

值得庆幸的是，所有 Backstage 核心包在实现上保证了包重复（package duplication）不会引发问题。例如以下包的重复安装都是可接受的：

@backstage/core-plugin-api
@backstage/core-components
@backstage/plugin-catalog-react
@backstage/backend-plugin-api

不过，即便包重复在多数情况下无害，你仍然可能出于优化 bundle 体积与安装速度的目的希望去重。官方推荐使用yarn dedupe等去重工具来精简重复包的数量。

代理（Proxy）配置

在企业内网等受限网络环境下，升级命令需要正确的代理配置才能正常工作。

CLI 的代理支持

Backstage CLI 在设置了NODE_USE_ENV_PROXY=1时会遵循标准的HTTP_PROXY、HTTPS_PROXY与NO_PROXY环境变量。完整细节参见企业代理指南。

Yarn 的代理设置

Yarn 有时也需要自己的代理配置，且其使用的配置项与其他模块不同。如果你决定使用上述 Backstage Yarn 插件，还需要额外设置代理值：

如果所有环境、所有场景下都需要代理，可以把httpProxy和httpsProxy写进yarnrc.yml文件；
如果只有部分环境需要代理（例如开发者工作站需要、而跑在云上的 CI 构建服务器不需要），则不建议修改yarnrc.yml，而是在需要代理的环境中设置环境变量YARN_HTTP_PROXY和YARN_HTTPS_PROXY。

:::warning如果你计划使用 Backstage Yarn 插件，必须在安装插件和运行versions:bump时都配置好这些额外的 yarn 代理设置。如果你不打算使用该插件，则似乎仅配置上述 CLI 代理设置即可。 :::

示例配置

export HTTP_PROXY=http://proxy.company.com:8080 export HTTPS_PROXY=http://proxy.company.com:8080 export NO_PROXY=localhost,internal.company.com export NODE_USE_ENV_PROXY=1 export YARN_HTTP_PROXY=${HTTP_PROXY} # optional export YARN_HTTPS_PROXY=${HTTPS_PROXY} # optional

回滚数据库迁移（Rollback migrations）

在某些情况下，你可能需要降级 Backstage 实例——例如因为某个版本出现问题，或者正在使用测试环境验证新版本。由于数据库迁移通常与代码版本绑定，降级时往往需要同时回滚数据库迁移。

可以参阅使用 Knex 手动回滚指南，了解如何使用 Knex 回滚迁移。这为"升级后发现问题需回退"的场景提供了一条明确的兜底路径，与本文前述的versions:bump --release <旧版本>降级手段配合，可以构成完整的升级-回退闭环。

总结：一条完整的升级工作流

综合以上内容，一个推荐的 Backstage 升级流程是：

准备：确认 yarn 版本 ≥ 4.1.1，在需要时安装 Backstage Yarn 插件（yarn plugin import https://versions.backstage.io/v1/tags/main/yarn-plugin），并确保backstage.json纳入版本控制与 CI/CD 产物；
升级：执行yarn backstage-cli versions:bump（或按需追加--release next/--release <version>/--pattern '<glob>'），由命令自动完成 package.json 批量改写、lockfile 更新、backstage.json版本写入与破坏性变更预警；
核对：查阅命令输出的 breaking changes 清单、@backstage/create-app的 CHANGELOG 以及模板变更提示（Upgrade Helper 链接），确认是否需要对app/backend结构做适配；
去重（可选）：使用yarn dedupe精简因跨包版本差异产生的重复依赖；
验证与回滚：在测试环境充分验证；如遇问题，使用versions:bump --release <旧版本>降级，并按需参考 Knex 手动回滚指南回滚数据库迁移。

【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析