Backstage v1.20.0 发布详解：React 18 官方支持、新前端系统路由体系与 OpenAPI 工具链落地-平芜编程栈

Backstage v1.20.0 发布详解：React 18 官方支持、新前端系统路由体系与 OpenAPI 工具链落地

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

本文基于 docs/releases/v1.20.0-changelog.md 完整梳理 Backstage v1.20.0 的 3723 行变更记录，聚焦三大主线：全栈 React 18 官方支持、实验性新前端系统（new frontend system）路由与扩展体系的演进、以及围绕 OpenAPI 的后端类型安全与测试工具链落地，并逐一解读 Catalog、Scaffolder、Auth、TechDocs、Search 等核心插件的关键变更与升级注意事项。读完本文，你将掌握 v1.20.0 中每个破坏性变更的迁移方法、新配置项的语义与默认值，以及如何在现有 Backstage 应用中安全升级。

一、版本纵览：v1.20.0 的几条主线

v1.20.0 是一次跨前后端、覆盖面极广的版本发布，涉及@backstage/cli、core-plugin-api、frontend-app-api、frontend-plugin-api、backend-openapi-utils、repo-tools、plugin-catalog、plugin-catalog-backend、plugin-scaffolder、plugin-auth-backend、plugin-techdocs等数十个包。整体来看可以归纳为五条主线：

React 18 官方支持：几乎所有前端包都打上了6c2b872153: Add official support for React 18的补丁标记，包括core-plugin-api@1.8.0、core-app-api@1.11.1、core-components@0.13.8、app-defaults@1.4.5、frontend-app-api@0.3.0及全部插件。
新前端系统（new frontend system）持续成型：frontend-plugin-api@0.3.0引入新的RouteRef/SubRouteRef/ExternalRouteRef类型体系，frontend-app-api@0.3.0支持通过app.routes.bindings配置路由绑定，并新增AppTreeApi。
OpenAPI 工具链正式落地：新包@backstage/backend-openapi-utils@0.1.0提供OPENAPI_SPEC_ROUTE（/openapi.json）标准端点与wrapInOpenApiTestServer测试辅助，@backstage/repo-tools@0.4.0新增schema openapi test命令。
Catalog 性能与展示层升级：引入catalog.stitchingStrategy.mode（immediate/deferred）可选配置，以及新的EntityPresentationApi。
Scaffolder 表单体系重构：升级到@rjsf/*v5 系列，next版本字段扩展 API 被提升为正式公开接口。

二、React 18 官方支持：全栈范围内的统一升级

v1.20.0 中，React 18 支持不再只是个别包的实验能力，而是被提升为官方支持。这一变更横跨了core-plugin-api、core-app-api、core-components、theme、version-bridge、test-utils、app-defaults以及 catalog、scaffolder、techdocs、search、playlist、home、kubernetes、graphiql 等几乎所有前端插件包。

在 core-plugin-api 侧，IconComponent现在支持fontSize: 'inherit'，便于行内图标的使用（变更1e5b7d993a）；同时引入AnyRouteRefParams作为已被废弃的AnyParams的替代（变更cb6db75bc2）。

在渲染层，core-app-api与dev-utils中react-dom/client的加载方式从require(...)切换为动态import(...)（变更67cc85bb14），并使用 React 18 的createRootAPI（变更38cda52746）。这意味着：

升级到 v1.20.0 后，应用可以放心使用 React 18 的并发特性；
前端渲染入口不再与 CommonJS 的require强绑定，为后续 ESM 化铺路。

从仓库示例看，packages/app-legacy 与 packages/app 都随版本同步升级依赖，作为官方升级模板可直接参考其package.json的依赖组合。

三、新前端系统演进：新的路由体系与 AppTreeApi

v1.20.0 是新前端系统（new frontend system）演进的重要里程碑，核心变化集中在@backstage/frontend-plugin-api@0.3.0与@backstage/frontend-app-api@0.3.0两个包。

3.1 新的 RouteRef 类型体系

frontend-plugin-api@0.3.0新增了RouteRef、SubRouteRef、ExternalRouteRef及相关类型，并让本包所有导出不再依赖core-plugin-api中的同名旧类型（变更68fc9dc60e）。与此同时，core-plugin-api@1.8.0对旧路由系统中的若干类型及 route ref 上的字段进行了废弃标记，并新增/alpha导出工具convertLegacyRouteRef：

// 旧路由 ref 与新前端系统 API 之间的临时桥接 import { convertLegacyRouteRef } from '@backstage/core-plugin-api/alpha';

该工具的存在意味着 v1.20.0 正处于新旧路由体系并存的过渡期：已用新前端系统组装应用（createApp）的开发者，可以通过convertLegacyRouteRef让存量 route ref 继续工作。

3.2 createApp 路由绑定与 AppTreeApi

frontend-app-api@0.3.0的关键能力是：createApp使用的路由系统已替换为仅支持frontend-plugin-api新格式 route ref 的实现，并且不再要求 route ref 的 ID 与其关联的扩展 ID 相同。应用可以通过app.routes.bindings配置绑定路由（变更68fc9dc60e）。

同时，v1.20.0 将内部 "app graph" 重构为 "app tree"，并实现新的AppTreeApi（变更733bd95746、4d6fa921db），扩展实例系统整体被 app tree 取代。createApp的 options 参数现在变为可选（变更fdc348d5d3），传入的 features 会按引用与 ID 双重去重，且显式传入的 features 优先级高于自动发现与加载的 features（变更685a4c8901）。

3.3 扩展工厂输出方式变更

frontend-plugin-api@0.3.0中，扩展的工厂函数改为直接返回输出，而不再调用bind(...)（变更77f009b35d）。这是一个面向新前端系统插件作者的行为级变更，任何基于该包早期实验版本编写的扩展都需要同步调整。core-plugin-api还新增了默认的扩展 Suspense 组件以改善加载体验（变更6af88a05ff）。

3.4 各插件的 alpha 声明式扩展

v1.20.0 中大量插件通过/alpha子路径发布了面向新前端系统的声明式扩展：

Catalog（plugin-catalog@1.15.0）：新增 sidebar item、index page、filter 等声明式扩展预设，并给出初始的实体页实现（0bf6ebda88、bb98953cb9），overview 页默认启用、about card 作为可选卡片；
TechDocs（plugin-techdocs@1.9.0）：导出 alpha 路由与导航项扩展（a3add7a682），并新增实体页内容（0bf6ebda88）；
Home（plugin-home@0.5.10）：通过/alpha子路径支持声明式集成（5b364984bf）；
Catalog Import（plugin-catalog-import@0.10.2）：创建与声明式集成系统兼容的实验插件（6db75b900a）；
Stack Overflow（plugin-stack-overflow@0.1.22）：迁移到新前端系统（b168d7e7ea）；
Search / User Settings / Tech Radar 等：均更新了 alpha 导出以适配新的路由体系（68fc9dc60e）。

提示：/alpha子路径导出属于实验性 API，仅适用于使用新前端系统的应用，正式生产应用建议等待其 GA。

四、后端 OpenAPI 工具链：从规范校验到运行时测试

v1.20.0 最值得关注的底层能力建设，是全新的@backstage/backend-openapi-utils@0.1.0包与配套的 repo-tools 命令。

4.1 标准化的 /openapi.json 端点

backend-openapi-utils@0.1.0为所有经过校验的路由器（validated router）新增了/openapi.json标准端点，用于在统一路径上暴露完整的 OpenAPI 规范（变更785fb1ea75）。在源码中该路由常量定义于 constants.ts：

export const OPENAPI_SPEC_ROUTE = '/openapi.json';

而路由实现位于 stub.ts：当请求到达/openapi.json时，会使用openapi-merge将当前插件挂载的 base path 前插到规范中（prepend: req.originalUrl.replace(OPENAPI_SPEC_ROUTE, '')），从而保证返回的 spec 中 server/path 与实际部署位置一致。createValidatedOpenApiRouter则基于express-openapi-validator构建带请求校验（默认coerceTypes: false、allowUnknownQueryParameters: false）的 typed router。

4.2 wrapInOpenApiTestServer 与 schema openapi test

补丁变更6694b369a3为backend-openapi-utils增加了wrapInOpenApiTestServer，允许在运行时对请求做代理，用于支撑新的yarn backstage-repo-tools schema openapi test命令。在 testUtils.ts 中可以看到其雏形wrapServer：它启动一个捕获型 Proxy，将 Express 应用的监听端口指向代理端口，从而让所有请求/响应都经过 OpenAPI 规范一致性校验，并通过afterAll钩子统一清理代理资源。

配套地，@backstage/repo-tools@0.4.0新增了schema openapi test命令（变更6694b369a3），它基于 Optic 引擎，用你的测试数据对 OpenAPI spec 做运行时校验。使用前需在仓库根目录安装依赖：

yarn add @useoptic/optic

之后即可运行：

yarn backstage-repo-tools schema openapi test

这套工具链的意义在于：Backstage 的 OpenAPI 校验从"构建期静态类型"延伸到"运行期行为验证"，catalog-backend 与 search-backend 在本版本中也同步更新了更完整的错误响应与请求体 spec（同样基于 Optic），并把测试用例切换到backend-openapi-utils提供的 supertest 直通能力。

4.3 将插件 OpenAPI spec 纳入 Catalog

新包@backstage/plugin-catalog-backend-module-backstage-openapi@0.1.0提供一个新的 catalog 模块，用于把 Backstage 插件自身的 OpenAPI spec摄取进 Catalog 并展示为 API 实体（变更785fb1ea75）。结合上一节的标准端点，这形成了一个闭环：插件通过/openapi.json暴露 spec，catalog 模块定时抓取并建模为API类型实体，再通过 api-docs 插件呈现。这也解释了example-backend-next的依赖清单中为什么会新增该模块。

五、Catalog：stitching 策略、展示层 API 与扩展点

5.1 新增 catalog.stitchingStrategy.mode 配置

plugin-catalog-backend@1.15.0引入可选配置catalog.stitchingStrategy.mode（变更8d756968f9），取值为：

取值	默认	行为
`immediate`	是	与升级前行为一致：每个 processing 任务完成后立即（in-band、阻塞）执行 stitching
`deferred`	否	将 stitching 推迟到独立的异步 worker 队列上执行，与 processing 解耦

catalog: stitchingStrategy: mode: deferred # 可选：'immediate'（默认） | 'deferred'

适用场景：当大批量摄取实体、且实体之间关系呈现"扇形展开/收敛"（fan-out / fan-in）规模很大时，deferred模式可以平滑吞吐、降低 p99 处理时延，并避免热点实体被反复过度 stitching。代价是引入队列带来的额外墙钟时间开销。从源码看，DefaultProcessingDatabase与DefaultProviderDatabase中已存在deferredEntities的完整处理链路（见 DefaultProcessingDatabase.ts 与 DefaultProviderDatabase.ts），deferred 实体会被写入refresh_state表等待后续处理。

5.2 新的 EntityPresentationApi

plugin-catalog-react@1.9.0新增EntityPresentationApi与entityPresentationApiRef（变更1e5b7d993a），用于统一控制实体引用（链接、标题、图标等）在 UI 中的呈现方式。plugin-catalog@1.15.0提供默认实现DefaultEntityPresentationApi，它会按需批量抓取并缓存 catalog 数据，同时允许采纳方注册自定义渲染函数。

配套变化：

EntityRefLink/EntityRefLinks组件改用该 API 渲染更准确的实体引用；fetchEntities与getTitleprops 被废弃；
新增EntityDisplayName组件（与EntityRefLink类似但无链接）；
EntityRefLink图标按 Material-UI 规范移到左侧，且支持hideIcons避免双图标（69c14904b6）；
catalog-graph@0.3.0将完整Entity对象加入EntityNodeData，并废弃name、kind、title、namespace、spec等冗余字段（a604623324）：

import { DEFAULT_NAMESPACE } from '@backstage/catalog-model'; const { kind, metadata: { name, namespace = DEFAULT_NAMESPACE, title }, } = entity;

5.3 位置分析（Location Analyzer）扩展点

catalog-backend@1.15.0与catalog-node@1.5.0新增 catalog 分析扩展点，支持注册 location analyzers，同时把AnalyzeOptions与ScmLocationAnalyzer类型迁移到@backstage/plugin-catalog-node（变更e5bf3749ad），catalog-backend-module-github也已改为从新位置导入这些类型。

5.4 其他 Catalog 修复

UserListPicker性能改进：不再依赖EntityListContext推断 owned/starred 数量，改为异步加载，并为其导出的过滤器实现getCatalogFilters方法（1fd53fa0c6）；
实体的spec.lifecycle、spec.type字段现在始终按字符串渲染（71c97e7d73）；
MissingAnnotationEmptyState迁移至plugin-catalog-react导出（6c357184e2），core-components 中的旧组件被废弃（0c5b78650c）。

六、Scaffolder：rjsf v5、任务回收配置与模板按钮文案

6.1 rjsf 升级到 v5，next 能力转正

plugin-scaffolder@1.16.0与plugin-scaffolder-react@1.6.0完成设计改进并支持@rjsf/*v5（变更3fdffbb699），这是本版本中最容易引发编译错误的变更：

原先的createNextFieldExtension、NextScaffolderPage已提升为正式 API：createScaffolderFieldExtension与ScaffolderPage；
旧导入位置@backstage/plugin-scaffolder/alpha、@backstage/plugin-scaffolder-react/alpha失效，需改从@backstage/plugin-scaffolder与@backstage/plugin-scaffolder-react导入；
如果遇到兼容问题，旧实现以createLegacyFieldExtension、LegacyScaffolderPage的名义保留在/alpha，但下一个主版本会移除；
@rjsf/utils、@rjsf/core、@rjsf/material-ui、@rjsf/validator-ajv8统一升级到5.13.6；
scaffolder-common为Template.v1beta3.schema.json补充了缺失的必填属性type（2e0cef42ab）。

6.2 模板级控制按钮文案

现在可以在每个模板中定义按钮文案（Back / Create / Review）（76d07da66a），scaffolder-react同时修复了非运行中任务的时间展示问题（dda56ae265）。

6.3 任务回收（Janitor）可配置化

plugin-scaffolder-backend@1.19.0将过期任务回收改为可配置（变更f3ab9cfcb7），暴露两个配置项：

scaffolder: # 陈旧任务的扫描处理间隔 processingInterval: ... # 任务心跳超时阈值，超过即视为陈旧任务 taskTimeoutJanitorFrequency: ...

6.4 文件复制与 Git 动作增强

copyWithoutTemplating/copyWithoutRender支持 globby 负向匹配（7d5a921114）：可以包含整个子目录、同时排除某个文件让其继续参与模板渲染，避免维护冗长的排除清单；
publish:github:pull-requestaction 支持update: true（5e4127c18e），可更新已存在的 PR；
大量 action 补充了示例与测试：github:environment:create、github:webhook、github:deployKey:create、publish:github:pull-request、gitlab:projectAccessToken:create、publish:gerrit等。

七、Auth：StaticTokenIssuer、Okta 扩展作用域与 Vault 新后端系统

7.1 StaticTokenIssuer 与 StaticKeyStore

plugin-auth-backend@0.20.0新增StaticTokenIssuer与StaticKeyStore（变更bdf08ad04a），这是一种使用预定义公私钥对为 Authorization header 签名令牌的替代 token 签发器，适合需要固定密钥、可预测签名的集成场景（例如与外部系统共享验证公钥）。对应实现见 plugins/auth-backend/src/identity/StaticTokenIssuer.ts 与 plugins/auth-backend/src/identity/StaticKeyStore.ts，并配有 StaticTokenIssuer.test.ts 与 StaticKeyStore.test.ts 测试。

7.2 Okta additionalScopes 与 Microsoft 相关修复

oktaprovider 新增可选配置additionalScopes，可在默认作用域之上追加自定义作用域（f2fc5acca6）；
Microsoft provider 回退到此前实现（96c4f54bf6），并修复了 profile 头像缺失与外部作用域 access token 获取问题（头像尺寸从 48x48 调整为 96x96，fde212dd10）、client secret 标记、移除prompt=consent等；
Azure Active Directory 品牌更名为 Entra ID，相关 JSDoc 与错误消息同步更新（243c655a68）。

7.3 Vault 插件支持新后端系统

plugin-vault-backend@0.4.0增加对新后端系统（new backend system）的支持（a873a32a1f），迁移方式：

import { createBackend } from '@backstage/backend-defaults'; const backend = createBackend(); // ... 其他功能注册 backend.add(import('@backstage/plugin-vault-backend')); backend.start();

token 续期任务可通过配置文件定义调度：

vault: baseUrl: <BASE_URL> token: <TOKEN> schedule: frequency: ... # 例如每小时 timeout: ... # 其他调度选项：scope、initialDelay 等

调度语义：省略或设为false时不调度续期任务；设为true时按默认每小时续期；给出对象时使用自定义调度。同时VaultApi与VaultSecret被废弃，改从@backstage/plugin-vault-node导入（7a41bcf2af）。

八、CLI 与工具链：构建选项收敛与开发体验改进

8.1 移除 --experimental-type-build 与 alphaTypes/betaTypes

@backstage/cli@0.24.0移除了已废弃的--experimental-type-build选项（4e36abef14），并停止支持publishConfig.alphaTypes/publishConfig.betaTypes字段（8db5c3cd7a）。如需生成/alpha、/beta入口，请改用exports字段。cli-node@0.2.0同步移除相关支持。

8.2 从 @esbuild-kit 切换到 tsx

CLI 从已废弃的@esbuild-kit/*包切换到tsx，并在可用时使用新的register模块加载 API，消除了启动 backend 时的实验性警告（4ba4ac351f）。

8.3 EXPERIMENTAL_VITE 标志与 start 命令修复

新增EXPERIMENTAL_VITE环境标志，用于在开发时以 Vite 替代 Webpack 作为 dev server（e14cbf563d）；
start命令生成 backend 子进程时忽略stdin，修复 backend 启动挂起的问题（7cd34392f5）；
实验性包检测会忽略不提供package.json的包（6bf7561d3c）。

8.4 基础设施升级：knex 3 与 better-sqlite3 9

本版本将knex提升到 major 3、better-sqlite3提升到 major 9（013611b42e），这同时意味着 Node 16 不再受支持。在自有仓库中可按如下方式对齐依赖，以获取后续 Node 18+ 相关更新（参考 packages/create-app 的迁移模板）：

"dependencies": { // ... "knex": "^3.0.0" }, "devDependencies": { // ... "better-sqlite3": "^9.0.0" }

九、TechDocs、Search 与其他插件要点

9.1 TechDocs

plugin-techdocs@1.9.0：访问不存在的文档站点时发布新的not-foundanalytics 事件（17f93d5589）；修复跨页导航与浏览器前进/后退时的滚动位置问题（4728b3960d）；
plugin-techdocs-backend@1.9.0：暴露自定义构建策略的扩展点，DocsBuildStrategy类型迁移到plugin-techdocs-node，并废弃ShouldBuildParameters（67cff7b06f）；构建失败时补充实体信息（c3c5c7e514）；修复 build log transport 未提供时创建传输导致的内存泄漏（48a61bfdca）；
@techdocs/cli@1.7.0：运行 mkdocs server 前校验 Docker 状态（8600b86820）。

9.2 Search

新模块@backstage/plugin-search-backend-module-stack-overflow-collator@0.1.0从plugin-stack-overflow-backend中抽出，后者被废弃（46f0f1700e、b168d7e7ea）；collator 的requestParams现为可选，默认值为{ order: 'desc', sort: 'activity', site: 'stackoverflow' }；
plugin-search-backend-module-elasticsearch@1.3.10支持 AWS OpenSearch Serverless（不支持_refresh端点）；
plugin-search-backend-module-pg@0.5.16优化大表上过期文档删除逻辑（2b4cd1ccae）；
plugin-search-backend-node@1.2.11修复 Lunr 引擎对非字符串字段的高亮问题；
plugin-search-react@1.7.2将搜索 analytics 采集移入 search hook，并修复搜索框竞态问题（f48cde800a、f75caf9f3d）；
techdocs 搜索索引字段的定制流程被简化（c437253b7a）。

9.3 其他值得关注的变更

api-docs（0.10.0）：以 DocExplorer 取代 GraphiQL playground，并为swagger-ui-react的oauth2RedirectUrl定义默认值（0ac0e10822、62310404b7）；
Playlist（0.2.0）：支持自定义可组合的 Playlist 首页，但包含一个破坏性变更——PlaylistPage路由需手动接入：

-import { PlaylistIndexPage } from '@backstage/plugin-playlist'; +import { PlaylistIndexPage, PlaylistPage } from '@backstage/plugin-playlist'; <Route path="/playlist" element={<PlaylistIndexPage />} /> +<Route path="/playlist/:playlistId" element={<PlaylistPage />} />

Home（0.5.10）：新增FeaturedDocsCard组件，可按 filter 展示任意实体（302316d231）；修复retrieveAll未抓取访问记录的问题（d86b2acec4）；
backend-common（0.19.9）：数据库创建并发限制为 1（aa13482090）；
core-components（0.13.8）：修复 Safari <16.3 兼容性（消除extractInitials中的 RegExp lookbehind），RoutedTabs无 tabs 时不再崩溃，StructuredMetadataTable的options.titleFormat应用到包括嵌套在内的所有键；
user-settings-backend补充对@backstage/config的依赖（dd0350379b）。

十、升级路径与破坏性变更清单

基于 v1.20.0 changelog，升级到该版本时需要重点检查以下破坏性变更：

Playlist 路由拆分：必须手动添加<Route path="/playlist/:playlistId" element={<PlaylistPage />} />，否则播放列表详情页不可用。
Scaffolder 字段扩展 API 转正：将createNextFieldExtension/NextScaffolderPage的导入从/alpha改为正式包；旧 API 仅保留一个版本周期。
CLI 选项移除：删除--experimental-type-build与publishConfig.alphaTypes/betaTypes，改用exports字段定义/alpha、/beta入口。
Node 16 弃用：knex@3/better-sqlite3@9意味着运行环境需 Node 18+。
部分类型迁移：AnalyzeOptions/ScmLocationAnalyzer移至plugin-catalog-node；DocsBuildStrategy移至plugin-techdocs-node；VaultApi/VaultSecret移至plugin-vault-node；MissingAnnotationEmptyState改从plugin-catalog-react导入。
废弃项提示：AnyParams被AnyRouteRefParams取代；EntityNodeData上的name、kind、title、namespace、spec字段废弃；plugin-stack-overflow-backend与plugin-playlist中旧版相关能力废弃。

升级完成后，可以立刻验证两项新能力：访问任一已接入 OpenAPI 工具链的后端插件路由/openapi.json查看其规范输出；以及在 catalog 配置中尝试catalog.stitchingStrategy.mode: deferred观察大批量实体摄取时的性能表现。

十一、总结

v1.20.0 是 Backstage 在三个方向上同时发力的版本：全面拥抱 React 18，让全栈前端生态站在最新的渲染模型之上；新前端系统路由与扩展体系成型，app.routes.bindings、AppTreeApi、新RouteRef体系与/alpha声明式扩展共同勾勒出下一代前端插件的轮廓；OpenAPI 工具链闭环，从createValidatedOpenApiRouter、/openapi.json标准端点，到wrapInOpenApiTestServer与schema openapi test运行时校验，再到catalog-backend-module-backstage-openapi将 spec 建模为 Catalog 实体，为后端插件的契约化开发提供了完整支撑。与此同时，Catalog 的 deferred stitching、Scaffolder 的 rjsf v5 与任务回收配置、Auth 的 StaticTokenIssuer 等改进，则为生产环境的大规模实体管理、模板工程化与身份集成提供了更精细的控制能力。

如需逐包核对变更，可继续阅读仓库内的 docs/releases 目录下的各版本 changelog，或参考 packages/backend-openapi-utils、plugins/catalog-backend、plugins/scaffolder-backend、plugins/auth-backend 的源码与测试用例深入验证。

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

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