Backstage v1.15.0-next.0 变更日志深度解读：Material UI v5 支持、OwnerPicker 性能重构与破坏性变更清单

Backstage v1.15.0-next.0 变更日志深度解读：Material UI v5 支持、OwnerPicker 性能重构与破坏性变更清单

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

导读

本文基于 Backstage 官方仓库中的 v1.15.0-next.0 变更日志，逐项拆解这一预发布版本（pre-release）的核心改动：平台级 Material UI v5 支持方案与UnifiedThemeProvider迁移方法、EntityOwnerPicker的异步分页性能重构、GithubActionsClient的破坏性 API 调整，以及新增的plugin-home-react独立包与 Linguist 后端重构。读完本文，你将掌握 v1.15.0 升级时需要关注的破坏性变更、迁移步骤与源码级实现原理，并能在自己的 Backstage 应用中平稳完成升级。

说明：-next.0后缀表示这是 v1.15.0 正式版之前的预发布快照，仅用于提前验证与测试，不建议在生产环境直接升级。

一、平台级 Material UI v5 支持：主题体系进入双版本过渡期

1.1 本次改动要解决的问题

在 v1.15.0-next.0 之前，Backstage 前端组件与插件均基于 Material UI v4 构建。本次变更日志以同一提交1fd38bc4141a同时升级了三个核心包，宣布"平台级 Material UI v5 支持"（Material UI v5 Support）：

• @backstage/app-defaults@1.4.0-next.0
• @backstage/theme@0.4.0-next.0
• @backstage/test-utils@1.4.0-next.0

其核心设计思想是：在过渡期内同时支持 v4 与 v5 两套组件体系，让中心插件与组件可以逐步迁移到 v5，而存量 v4 实例与插件继续正常工作，避免一次性升级带来的兼容性冲击。

1.2 升级要点：改用 UnifiedThemeProvider

变更日志给出了明确的迁移指引：为了让未来的插件与组件能够使用 Material UI v5，需要将应用的AppTheme升级为使用UnifiedThemeProvider：

Provider: ({ children }) => ( - <ThemeProvider theme={lightTheme}> - <CssBaseline>{children}</CssBaseline> - </ThemeProvider> + <UnifiedThemeProvider theme={builtinThemes.light} children={children} /> ),

从源码看，UnifiedThemeProvider位于 packages/theme/src/unified/UnifiedThemeProvider.tsx，其实现要点如下：

• 双主题并行注入：内部通过theme.getTheme('v4')与theme.getTheme('v5')分别取出两个版本的 MUI 主题对象。若 v4 主题存在，则用StylesProvider+ThemeProvider（来自@material-ui/core/styles）包裹；若 v5 主题存在，则用StyledEngineProvider+ThemeProvider（来自@mui/material/styles）包裹，两个 Provider 层层嵌套实现共存。
• 类名隔离：为 v4 生成类名时使用createGenerateClassName({ productionPrefix: 'jss4-' })，并通过ClassNameGenerator.configure为 v5 组件统一加上v5-前缀，防止两套组件的样式类名在生产环境下冲突。
• 主题属性写入：通过useApplyThemeAttributes将主题模式（palette.type/palette.mode）与主题名（默认backstage）写入data-theme-*DOM 属性。

配套的测试文件 packages/theme/src/unified/UnifiedThemeProvider.test.tsx 与 API 报告 packages/theme/report.api.md 可帮助你进一步验证 Provider 的行为与公开 API 面。

1.3 对测试与 CLI 的连带影响

• @backstage/test-utils@1.4.0-next.0：Test App Wrapper 也已切换到UnifiedThemeProvider，使得测试环境可以同时承载 MUI v5 与 v4 组件。
• @backstage/cli@0.22.8-next.0：新增了Material UI v5 专属 lint 规则（提交20b7da6f1311），用于在构建阶段约束 MUI v5 的导入方式、最小化打包体积（bundle size）。

二、EntityOwnerPicker 性能重构：从全量预加载到异步分页

2.1 旧实现的问题

EntityOwnerPicker（实体所有者筛选器，用于 Catalog 页按 owner 过滤）的旧实现是：根据EntityListContext中已有的实体集合，一次性推断出可选的用户与用户组。当 Catalog 中实体数量庞大时，这种"全量预加载"方式会造成明显卡顿，且组件与列表上下文强耦合。

2.2 新实现的机制

本次变更（提交cb4c15989b6b）将EntityOwnerPicker重构为异步加载 + 滚动分页模式，并且不再依赖EntityListContext做推断，实现解耦。从当前仓库的 EntityOwnerPicker.tsx 可以看到关键实现细节：

• 异步数据获取：通过useFetchEntities钩子按需拉取所有者数据。该钩子定义在 useFetchEntities.ts，内部在owners-only模式下走useFacetsEntities（基于 facets 统计接口），在all模式下走useQueryEntities（基于查询接口），返回统一的[state, handleFetch, cache]结构。
• 输入防抖：使用useDebouncedEffect对搜索文本做 250ms 防抖后再触发handleFetch，避免每次击键都发起请求。
• 滚动加载更多：VirtualizedListbox虚拟化列表在滚动到底部且存在value.cursor时，调用handleFetch({ items: value.items, cursor: value.cursor })追加下一页数据——这就是"分批加载"的实现载体。
• 选中项缓存：通过useSelectedOwners内部的useRef<Record<string, Entity>>缓存已选 owner 的完整实体信息，保证已选内容不因分页而丢失。

配套测试见 EntityOwnerPicker.test.tsx。如果你在自己的应用中观察到 Catalog 页在实体规模较大时筛选下拉卡顿，升级后应能显著改善响应速度。

三、破坏性变更：GithubActionsClient 改采 scmAuthApi

3.1 变更内容

@backstage/plugin-github-actions@0.6.0-next.0增加了对GitHub Enterprise 自托管仓库的支持（提交96e1004e2a02），并伴随一个破坏性变更：

BREAKING：GithubActionsClient由接收githubAuthApi改为接收scmAuthApi。

scmAuthApi是 Backstage 面向多代码托管平台（GitHub / GitLab / Bitbucket 等）统一鉴权的 API，能够根据目标仓库的主机地址自动选择对应的凭据来源。这一调整使得 GitHub Actions 插件可以同时覆盖github.com与自托管 GitHub Enterprise 域名。

3.2 需要操作的人群

按变更日志原文，除非你自行构造GithubActionsClient，否则无需修改任何代码——依赖注入默认在插件内部完成。只有自定义客户端实例的应用需要把构造参数从githubAuthApi替换为scmAuthApi。

说明：plugin-github-actions由 Backstage 社区仓库维护，未包含在本仓库的plugins/目录内，本文相关结论以变更日志描述为准。

四、新包与模块化：plugin-home-react 独立发布

4.1 背景

@backstage/plugin-home-react@0.1.0-next.0是一个全新独立发布的包（提交41e8037a8a6d），核心动作是：把createCardExtension从plugin-home中抽取到新的plugin-home-react包，并对plugin-home中的旧导出标记为弃用（deprecated）。

4.2 迁移方式

从 plugins/home-react/src/extensions.tsx 可以看出，createCardExtension负责创建首页卡片扩展，支持title、components（懒加载的Content/Actions/Settings/ContextProvider部件）、layout（行列宽高配置）、settings（JSON Schema 设置）等选项。新包名意味着：

• 使用createCardExtension编写首页卡片时，应改为从@backstage/plugin-home-react导入；
• plugin-home中同名旧导出仍可用，但已被标记 deprecated，会在后续版本移除。

本次变更同时波及依赖该导出的plugin-home、plugin-stack-overflow等包（见其 Patch Changes），说明这是一次跨包的 API 收敛动作。当前仓库中plugin-home的 API 报告（如 plugins/home/report.api.md）里已出现多处@deprecated标记，可作为迁移时的对照清单。

五、Linguist 后端重构：接口化与 SQLite 支持

5.1 破坏性变更

@backstage/plugin-linguist-backend@0.3.0-next.0（提交bbf91840a52a）做了一次较大的内部重构，破坏性变更为：

• 移除LinguistBackendApi的公开构造函数；
• 不再导出LinguistBackendDatabase与LinguistBackendStore。

5.2 同时落地的改进

• LinguistBackendApi被转换为Interface（接口），并新增LinguistBackendClient作为其实现类；
• 新增SQLite 数据库支持，方便本地开发（此前仅支持 PostgreSQL 等）；
• 移除processes_date列的默认值；
• 处理顺序调整：未处理的实体（unprocessed）优先于过期实体（stale）被处理；
• 数据库中存在但 Catalog 中已删除的实体会被自动清理（orphan 清除）；
• 为LinguistBackendDatabase与LinguistBackendApi补充了测试；
• 改进了 README 的标题结构。

说明：plugin-linguist-backend同样由社区仓库维护，本仓库的plugins/下仅包含其前端plugin-linguist（0.1.4-next.0），后端结论以变更日志为准。

六、其他值得关注的修复与增强

6.1 Scaffolder 相关

• @backstage/plugin-scaffolder@1.13.2-next.0：当存在凭据时，为EventSource转发Authorization请求头（提交cda753a797b5），保证任务日志流在需要鉴权的环境下正常工作。
• @backstage/plugin-scaffolder-react@1.4.1-next.0：修复后端断连时前端无任何反馈的问题——现在会发送通用错误消息，并在15 秒后自动尝试重连（提交84a5c7724c7e）。
• @backstage/plugin-scaffolder-backend@1.14.1-next.0：
  • 修复catalog:register脚手架动作中optional属性的处理（提交cc936b529676）；
  • 为publish:gitlab:merge-request动作提供更清晰的错误消息（提交b269da39ac2d）。

6.2 搜索与探索

• @backstage/plugin-search-backend-module-explore@0.1.2-next.0：ToolDocumentCollatorFactory支持传入可选的tokenManager，用于对 collator 到 explore 后端的请求进行鉴权：

indexBuilder.addCollator({ schedule: every10MinutesSchedule, factory: ToolDocumentCollatorFactory.fromConfig(env.config, { discovery: env.discovery, logger: env.logger, + tokenManager: env.tokenManager, }), });

6.3 配置与权限

• @backstage/config-loader@1.3.1-next.0：修复key 中包含/的配置项被错误处理的 bug（提交f25427f665f7）。
• @backstage/plugin-jenkins-backend@0.2.1-next.0：通过 metadata endpoint 暴露权限定义（提交6c244b42cb06）；plugin-jenkins-common同步导出权限列表（提交35e11314d7e9）。
• @backstage/plugin-sonarqube-backend@0.1.11-next.0：提供完整的 config schema 定义，尤其用于保护 API Key 类敏感配置（提交0bb0b19b0da2）。

6.4 前端体验与稳定性

• @backstage/plugin-kubernetes@0.9.2-next.0：修复构建产物中的循环依赖（提交dc3cddf51ab5）；在PodDrawer 中展示错误信息（提交4b230b97660d）。
• @backstage/plugin-user-settings@0.7.4-next.0：登出后立即刷新 provider 的登录状态显示（提交7a8441b9a323）。
• @backstage/plugin-catalog-import@0.9.9-next.0：为"导入实体"按钮补充 analytics 事件（提交2ef84c05aee7）。
• @backstage/plugin-techdocs@1.6.3-next.0：将本地废弃引用改为从共享的plugin-techdocs-react导入（提交956d09e8ea68）。
• @backstage/plugin-techdocs-addons-test-utils@1.0.14-next.0：避免在清理阶段重复运行测试（提交1fd38bc4141a）。

6.5 文档一致性

多个插件（plugin-analytics-module-ga4、plugin-devtools-backend、plugin-dynatrace、plugin-entity-validation、plugin-pagerduty、plugin-techdocs-react、plugin-octopus-deploy、plugin-linguist-backend等）以提交3d11596a72b5统一了安装文档的写法，便于跨插件文档的检索与维护。

七、升级影响评估与行动清单

综合全文，升级到 v1.15.0-next.0（或后续正式版）时建议按以下清单逐项核对：

更完整的依赖矩阵可对照 example-app 与 example-backend 的依赖声明，以及变更日志中每个包下方的 "Updated dependencies" 区块。预发布版本请先在小规模测试环境验证后再决定是否纳入生产升级路径。

结语

v1.15.0-next.0 是 Backstage 向 Material UI v5 生态过渡的重要里程碑：UnifiedThemeProvider的双主题共存机制、EntityOwnerPicker的异步分页改造，以及围绕plugin-home-react与 Linguist 后端的模块化重构，共同勾勒出该版本"渐进式演进、可控破坏"的升级思路。升级前重点核对上述破坏性变更清单，即可平稳完成版本过渡。

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