企业官网建设流程全解析

Backstage 升级指南：使用 backstage-cli 与 yarn 插件保持实例与最新版本同步

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

Backstage 官方将自身定位为“框架/库”而非一次性交付的“应用”，因此@backstage/create-app生成的实例只是一个起点，需要跟随上游持续演进。本文基于 Backstage 官方文档 docs/golden-path/create-app/keeping-backstage-updated.md，完整讲解如何用backstage-cli versions:bump批量升级依赖、如何跟踪create-app模板变更、如何通过 Backstage yarn 插件管理包版本、如何处理依赖重复与代理环境，以及如何借助 Knex 手动回滚数据库迁移，帮助你在 monorepo 结构下安全、可复现地完成版本升级。

Backstage 是“库”而不是“应用”，版本需要持续跟进

Backstage 始终在持续改进，因此与最新 release 保持同步是运行维护的日常工作。与create-react-app类似，@backstage/create-app工具为你提供了一个“起点模板”，模板本身会随仓库演进，但你在create-app时生成的本地app与backend包并不会自动获得模板更新，需要你主动去升级。理解这一点是后续所有升级操作的前提。

使用 backstage-cli 批量升级版本

一条命令升级所有@backstage包

Backstage CLI 提供了专用命令versions:bump，它会把 monorepo 中所有@backstage包及依赖一次性升级到最新版本：

yarn backstage-cli versions:bump

之所以要“一次性”升级所有@backstage包，是因为这些包之间存在相互依赖关系（例如@backstage/core-plugin-api与@backstage/core-components版本需配套），逐个升级很容易破坏版本一致性。从源码看，该命令位于 packages/cli-module-migrate/src/commands/versions/bump.ts，核心流程为：

1. 加载根目录yarn.lock（Lockfile.load）；
2. 通过mapDependencies(targetPaths.dir, pattern)发现仓库内所有匹配 pattern 的依赖；
3. 并发（concurrencyFactor: 4）向 npm registry 查询各包的可用版本；
4. 将各包package.json中的版本范围统一改写为^<目标版本>；
5. 最后执行yarn install落地变更。

命令默认的处理范围是dependencies、devDependencies、peerDependencies、optionalDependencies四种依赖类型（见 bump.ts）。

跟随不同的 release 线

默认情况下，versions:bump会升级到每月发布一次的mainrelease 线。如果你希望更激进地跟踪每周发布的next线，可以指定--release选项：

yarn backstage-cli versions:bump --release next

源码中release参数默认值为main（见 bump.ts）。其解析逻辑（bump.ts）为：

• 若设置了环境变量BACKSTAGE_MANIFEST_FILE，则直接读取本地 manifest 文件；
• 若--release传的是合法 semver 版本号，则严格按该版本获取 manifest；
• 否则按 release 线（main/next）获取 manifest；其中next线会比较next与main两份 manifest 的releaseVersion，取较新者。

通过--pattern扩展升级范围

如果你还使用了其他组织维护的插件（例如@roadiehq/*），可以传--pattern扩展匹配范围，而不仅仅升级@backstage/*：

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

注意：源码会拒绝过宽的*通配符（Rejected pattern '*'，见 bump.ts），并要求 pattern 以/*结尾且能覆盖@backstage/前缀（extendsDefaultPattern）。测试用例 packages/cli-module-migrate/src/commands/versions/bump.test.ts 中包含了默认 pattern、自定义 pattern、--skip-install、指定精确版本等场景的验证，例如should bump backstage dependencies and dependencies matching pattern glob。

此外versions:bump还支持--skip-install（跳过yarn install步骤）与--skip-migrate（跳过已迁移包的迁移步骤）两个选项，适合在 CI 中分步执行。

跟踪 create-app 模板变更

@backstage/create-app命令基于模板生成初始结构，模板源位于本仓库的 packages/create-app。模板会定期更新，但本地已经生成好的app与backend包不会自动同步模板改动。因此：

• 模板的任何变更都会连同升级说明记录在@backstage/create-app包的 changelog（仓库中对应 packages/create-app/CHANGELOG.md）中，升级包时建议先翻阅该 changelog，确认是否有需要手动同步的模板改动；
• 也可以借助 Backstage Upgrade Helper 工具获得两个版本之间所有变更的汇总视图；
• 你当前安装的 Backstage 版本记录在仓库根目录的backstage.json中（该文件由 CLI 在创建应用时生成并维护），升级前先确认它，升级后再核验它是否被正确更新。

使用 Backstage yarn 插件管理包版本

插件解决什么问题

在传统方式下，升级时需要逐个修改 monorepo 中每个package.json里的@backstage依赖版本，且新增依赖时还要手动查“当前 release 对应哪个版本”。Backstage yarn 插件（本仓库实现位于 packages/yarn-plugin）通过引入backstage:^版本协议解决了这个问题：它会根据backstage.json中记录的整体 Backstage 版本，为每个包自动确定合适的版本。

安装要求

使用该插件要求 yarn 版本为4.1.1 或更高。插件源码在启动时会用semverUtils.satisfiesWithPrereleases(YarnVersion, '^4.1.1')做版本校验，不满足时直接打印错误并建议yarn plugin remove @yarnpkg/plugin-backstage（见 packages/yarn-plugin/src/index.ts）。

安装步骤

在 Backstage monorepo 根目录执行：

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

该命令会向.yarnrc.yml写入插件配置并下载插件 bundle，产生的文件系统变更应提交到版本库。官方建议在准备进行 Backstage 升级时安装该插件，这样更容易确认一切工作正常——因为versions:bump会检测到插件存在，并自动把整个 monorepo 的依赖迁移到backstage:^协议（相关行为在测试 bump.test.ts 中有明确覆盖，日志会提示 “this bump used backstage:^ versions … To migrate back to explicit npm versions, remove the plugin … then repeat this command”）。

使用方式

插件安装后，已发布@backstage包的版本可以替换为字符串"backstage:^"：

{ "dependencies": { "@backstage/core-app-api": "backstage:^", "@backstage/core-components": "backstage:^" } }

backstage:^的语义类似 yarn workspaces 的workspace:范围：本地解析时始终取backstage.json中对应 Backstage release 在 manifest 里记录的精确版本；若依赖包被发布，则版本会以^前缀形式出现。

注意：backstage.json是插件工作的关键文件，务必确保它被包含在 CI/CD 流水线和容器构建产物中，否则插件将无法确定目标版本。

插件的底层实现原理

从 packages/yarn-plugin/README.md 的 Architecture 一节可以了解其内部机制，插件由以下组件协同工作：

• reduceDependencyhook：在 yarn 解析工作区直接/间接依赖时被调用，把backstage:^改写为带参数的backstage:^::backstage=<版本>&npm=<版本>。实现见 packages/yarn-plugin/src/handlers/reduceDependency.ts：只接受 selector 为^的范围，否则抛错；随后通过getCurrentBackstageVersion()读取backstage.json中的版本、通过getPackageVersion()从 manifest 取 npm 包版本并绑定到 descriptor 上；
• BackstageNpmResolver：负责把backstage:描述符解析为对应的 npm 包，实现见 packages/yarn-plugin/src/resolvers/BackstageNpmResolver.ts。它从 descriptor 的npm参数取出版本，委托NpmSemverResolver处理，并在getResolutionDependencies中额外插入npm:^<版本>描述符——这样 lockfile 中同时保留backstage:^与对应npm:^两条记录，确保在发布包或用backstage-cli build-workspace构建 dist workspace 时（backstage:^与npm:范围互相切换）不会意外解锁依赖；
• beforeWorkspacePackinghook：发布打包前把所有backstage:^替换回对应 npm 版本范围，保证发布到 npm 的包不包含自定义协议；
• afterWorkspaceDependencyAddition/afterWorkspaceDependencyReplacementhook：插件把既有依赖转成backstage:^后，新增的@backstage/*依赖也会自动被改写为backstage:^；当yarn add一个已是目标包依赖的@backstage/*包时会打印警告，提醒该操作会把backstage:^替换为实际 npm 版本范围，可能并非你所期望。

插件还支持两个环境变量用于离线/内网环境：

• BACKSTAGE_VERSIONS_BASE_URL：版本 manifest 的基础 URL，默认为https://versions.backstage.io/v1/releases/VERSION/manifest.json（注意只填主机部分，路径由插件追加），适合通过镜像或代理访问；
• BACKSTAGE_MANIFEST_FILE：本地 manifest 文件路径，设置后插件不再从网络获取 manifest，适合完全无外网的环境。

深入理解依赖不匹配（duplicate dependencies）

Backstage 采用 Yarn workspaces 结构的 monorepo，app、backend以及你添加的自定义插件都是拥有独立package.json和依赖的独立包：

• 当某个依赖在不同包中的版本相同时，yarn 会把它提升（hoist）到 monorepo 根目录的node_modules中共享；
• 当出现不同版本时，yarn 会在对应包内部创建各自的node_modules，导致同一应用中出现同一包的多个版本。

所有 Backstage 核心包在实现上都保证“包重复不是问题”，例如@backstage/core-plugin-api、@backstage/core-components、@backstage/plugin-catalog-react、@backstage/backend-plugin-api的重复安装都是可接受的。尽管如此，为优化 bundle 体积与安装速度，仍建议使用yarn dedupe之类的去重工具削减重复包数量。

代理环境（Proxy）配置

Backstage CLI 在设置NODE_USE_ENV_PROXY=1时会遵循标准的HTTP_PROXY、HTTPS_PROXY、NO_PROXY环境变量，完整细节参见 docs/tutorials/corporate-proxy.md。

此外，在受限网络环境中yarn本身有时也需要代理配置，且它的配置方式与其他模块不同：

• 如果使用上文提到的 Backstage yarn 插件，必须额外配置 yarn 的代理值才能安装插件并运行versions:bump命令；
• 如果所有环境都需要代理，可在.yarnrc.yml中添加httpProxy和httpsProxy配置；
• 如果只有部分环境需要（如开发机需要、AWS 上的 CI 构建机不需要），则不建议改.yarnrc.yml，而是在需要的环境中设置环境变量YARN_HTTP_PROXY与YARN_HTTPS_PROXY；
• 如果不打算使用 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 实例，例如新版本出现问题，或是在测试环境中验证新版本后再回退。数据库迁移的回滚可参考 docs/tutorials/manual-knex-rollback.md，该指南讲解了如何使用 Knex 手动回滚迁移：Backstage 后端插件（如 catalog、scaffolder 等）的数据库迁移记录在各自的migrations目录中，每个迁移按顺序执行并记录于 schema 的迁移表内，手动回滚时需要确认当前迁移序号，再通过 knex CLI 执行对应次数的down。这一操作通常在“升级后发现兼容性问题、需要临时回到旧版本”的场景下与版本降级配合使用。

小结：一份完整的升级检查清单

1. 确认根目录backstage.json中记录的当前版本；
2. （推荐）安装 Backstage yarn 插件：yarn plugin import https://versions.backstage.io/v1/tags/main/yarn-plugin，并确认 yarn ≥ 4.1.1；
3. 查阅@backstage/create-app的 changelog（packages/create-app/CHANGELOG.md）确认是否有需要手动同步的模板变更；
4. 执行yarn backstage-cli versions:bump（默认main线）或yarn backstage-cli versions:bump --release next（跟踪周更）；
5. 若需同时升级其他生态插件，追加--pattern '@{backstage,roadiehq}/*'；
6. 在受限网络环境中按需配置 CLI 代理与 yarn 代理环境变量；
7. 提交versions:bump产生的package.json、yarn.lock、.yarnrc.yml与backstage.json变更；
8. 升级后如有异常，可借助 docs/tutorials/manual-knex-rollback.md 回滚数据库迁移，再降级相关包。

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