Backstage v1.30.0-next.4 版本解读：前端插件覆盖机制、Catalog 实体扩展与通知系统增强-开发者社区

Backstage v1.30.0-next.4 版本解读：前端插件覆盖机制、Catalog 实体扩展与通知系统增强

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

本篇文章针对 Backstage（开源开发者门户框架）的v1.30.0-next.4预发布版本变更日志进行技术解读，覆盖该版本中 frontend-plugin-api 的扩展覆盖（Extension Overrides）机制、catalog-model 的 Domain/System 实体spec.type属性、Cloudflare Access 认证增强、通知系统默认已读行为，以及 Scaffolder、TechDocs 等核心插件的一系列修复。读者读完本文后，将能理解本次版本中 API 层面的破坏性变更与新增能力，并能直接使用withOverrides、Extension.override、plugin.getExtension等新 API 定制自己的 Backstage 插件，同时掌握升级到该版本时需要关注的依赖与行为变化。

该版本为1.30.0的第四个预览版本（next.4），共涉及 70 余个@backstage/*包及示例应用的变更，其中大部分为依赖升级（Patch），真正的功能性变化（Minor）集中在@backstage/frontend-plugin-api、@backstage/catalog-model、@backstage/plugin-auth-backend-module-cloudflare-access-provider、@backstage/plugin-notifications与@backstage/plugin-scaffolder五个包上。

一、前端插件系统：扩展覆盖 API 全面落地

本次版本在前端插件系统（New Frontend System）上的改动最为密集，也是开发者升级后最需要关注的 API 变化。相关实现集中在 createFrontendPlugin.ts 与 createExtension.ts 中。

1.1`plugin.withOverrides`：应用内整体覆盖插件扩展

变更99abb6b为前端插件引入了全新的plugin.withOverrides方法，用于在不修改插件源码的前提下，在应用侧整体覆盖插件内任意扩展的定义。日志中给出的示例为：

import homePlugin from '@backstage/plugin-home'; export default homePlugin.withOverrides({ extensions: [ homePage.getExtension('page:home').override({ *factory(originalFactory) { yield* originalFactory(); yield coreExtensionData.reactElement(<h1>My custom home page</h1>); }, }), ], });

从源码看，withOverrides定义在OverridableFrontendPlugin接口上（createFrontendPlugin.ts），其options支持四个覆盖维度：

extensions：要新增或覆盖的扩展定义列表。若某个扩展的 ID 与插件原有扩展 ID 相同，则在原注册位置就地替换（保持原有挂载顺序），其余新增扩展则追加在末尾——这一顺序语义对应用的扩展挂载顺序至关重要；
if：覆盖整个插件所有扩展共享的启用条件（FilterPredicate）；
title/icon：覆盖插件在页面头部与导航中的显示标题与图标；
info：逐个覆盖插件原始的 info 加载器（package.json 与 manifest）。

withOverrides的返回值仍然是OverridableFrontendPlugin，因此支持链式调用，多次叠加覆盖。实现上，createFrontendPlugin.ts 内部会通过resolveExtensionDefinition解析覆盖扩展的 ID、通过throwOnDuplicateExtensionIds拒绝重复 ID，再合并出新的扩展列表后重新调用createFrontendPlugin生成一个新插件实例。

1.2`plugin.getExtension`：按 ID 获取扩展定义

变更a65cfc8新增了plugin.getExtension(id)方法，允许从插件实例上按 ID 取回扩展定义，前提是该扩展使用 v2 格式（通常即扩展蓝图 Blueprint）定义。从源码可见其行为（createFrontendPlugin.ts）：ID 不存在时会抛出Attempted to get non-existent extension '${id}' from plugin '${pluginId}'错误，因此在使用前应确保插件确实注册了对应 ID 的扩展。这一方法与withOverrides组合使用，即上一节示例中homePage.getExtension('page:home').override(...)的完整调用链。

1.3 扩展定义覆盖：`Extension.override`与 Blueprint 工厂覆盖

变更2d21599为扩展定义本身增加了override能力，日志给出了完整的实体卡片覆盖示例：

const TestCard = EntityCardBlueprint.make({ ... }); TestCard.override({ // override attachment points attachTo: { id: 'something-else', input: 'overridden' }, // extend the config schema config: { schema: { newConfig: z => z.string().optional(), } }, // override factory *factory(originalFactory, { inputs, config }){ const originalOutput = originalFactory(); yield coreExentsionData.reactElement( <Wrapping> {originalOutput.get(coreExentsionData.reactElement)} </Wrapping> ); } });

源码层面（createExtension.ts）对override施加了如下约束：

只能覆盖以"新格式"（outputs 为数组）声明的扩展，否则报错Cannot override an extension that is not declared using the new format with outputs as an array；
覆盖output时必须同时覆盖factory（Refused to override output without also overriding factory）；
params与factory不能同时覆盖（Refused to override params and factory at the same time）；
覆盖工厂后，可通过originalFactory()获取原始工厂输出，再从返回的数据容器中按数据键取出（如originalOutput.get(coreExentsionData.reactElement)），实现"包装原始输出"的叠加式定制。

1.4 Blueprint 的`.make`与`.makeWithOverrides`拆分

变更264e10f将 Blueprint 上原有的.make方法重构为两个：

.make：面向简单场景，仅通过高阶参数（attachTo、name、namespace等标准参数）创建扩展实例；
.makeWithOverrides：面向高级场景，允许覆盖更多内容（配置 schema、inputs、output、factory 等），对最终扩展有更细粒度的控制。

同时，264e10f还废弃了旧的ExtensionCreators，统一迁移到 Blueprint 体系。这意味着基于旧版 Extension Creator API 的代码在升级后应迁移到对应的createExtensionBlueprint体系。另外，变更6f72c2b修复了扩展蓝图inputs合并的问题，变更34f1b2a明确了语义：inputs支持合并，但output不再合并，且蓝图中的原始工厂现在返回一个数据容器——它既能提供对返回数据的访问，也可以作为 output 整体转发。这些改动均可在 createExtension.ts 及对应测试 createFrontendPlugin.test.ts 中验证。

二、Catalog 模型：Domain 与 System 实体新增可选`spec.type`

变更34fa803为catalog-model（1.6.0-next.0）中的Domain与System两种实体 Kind 引入了可选的spec.type属性。这是本版本中少数直接影响用户 catalog-info.yaml 数据模型的改动。

从源码定义可以看到类型层面的变化：

DomainEntityV1alpha1.ts：spec字段为{ owner: string; subdomainOf?: string; type?: string; }；
SystemEntityV1alpha1.ts：spec字段为{ owner: string; domain?: string; type?: string; }。

type是可选属性，因此对存量数据完全向后兼容——未提供spec.type的 Domain/System 实体仍然合法。其典型用途是表达领域/系统的业务分类（例如领域属于"支付""风控"等类型），前端与搜索等下游可以基于该字段做过滤与分组展示。对应的 JSON Schema 校验位于 packages/catalog-model/src/schema/kinds 目录下，测试用例可参考 DomainEntityV1alpha1.test.ts 与 SystemEntityV1alpha1.test.ts。

注意：Domain/System仍同时支持backstage.io/v1alpha1与backstage.io/v1beta1两个 API 版本，实体模型注册逻辑见两个文件底部的domainEntityModel/systemEntityModel（createCatalogModelLayer构建，relation 关系ownedBy、partOf不变）。

三、认证：Cloudflare Access 自定义头与 Cookie 支持

变更75d026a为@backstage/plugin-auth-backend-module-cloudflare-access-provider（0.2.0-next.3）增加了对Cloudflare Custom Headers与Custom Cookie Auth Name的支持。该模块用于将 Cloudflare Access（Zero Trust 网关）作为 Backstage 的身份认证来源，此前仅支持默认的Cf-Access-Jwt-Assertion请求头与默认 Cookie 名。升级后，若你的 Cloudflare Access 策略配置了自定义的 JWT 请求头名称或自定义 Cookie 名称，可以在 provider 配置中对应指定，Backstage 将按自定义名称解析 JWT 断言。该 provider 同时依赖@backstage/backend-plugin-api（0.8.0-next.3）与@backstage/plugin-auth-node（0.5.0-next.3）的新版本。

四、通知系统：默认打开即读与无用户目录支持

4.1 打开 Snackbar/Web 通知链接即标记已读

变更0410fc9（@backstage/plugin-notifications@0.3.0-next.1）改变了通知的已读语义：默认情况下，当用户通过 Snackbar 弹窗或 Web 通知链接打开通知时，该通知会被自动标记为已读。这一行为可以从插件源码中得到印证——useWebNotifications.ts 中在处理 Web 通知时调用notificationsApi.updateNotifications({ ... })更新已读状态，而 NotificationsTable.tsx 也通过notificationsApi.getNotifications({ read: false })拉取未读列表并批量updateNotifications({ ids, read: true })。Snackbar 组件的配置入口位于 NotificationsSideBarItem.tsx，支持通过snackbarProps（enabled、autoHideDuration、anchorOrigin、iconVariant等）定制弹窗行为。

4.2 无目录用户也能使用通知

变更7a05f50（@backstage/plugin-notifications-backend@0.3.4-next.3）放宽了后端限制：允许在 Catalog 中不存在对应用户实体的情况下使用通知功能。此前通知系统强依赖 Catalog 中的 User 实体来解析收件人，对于尚未将全部用户同步进 Catalog 的团队，这一改动显著降低了通知功能的接入门槛。

五、Scaffolder：MyGroupsPicker 展示一致性

变更1552c33（@backstage/plugin-scaffolder@1.24.0-next.3）重做了 Scaffolder 中MyGroupsPicker字段的实体展示方式，改用entityPresentationApi渲染实体，使其与 Scaffolder 其他 picker 的展示保持一致。源码证据：MyGroupsPicker.tsx 中通过useApi(entityPresentationApiRef)获取 API，并在forEntity(item)调用后渲染实体展示信息，选项则使用EntityDisplayName组件（renderOption={option => <EntityDisplayName entityRef={option} />}）统一呈现；测试用例 MyGroupsPicker.test.tsx 中多次 mock 了entityPresentationApiRef来验证该行为。这保证了在 Catalog 中自定义了实体展示规则（如自定义头像、显示名称）的组织，在 Scaffolder 表单中也能得到一致的体验。

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

6.1 前端与核心库

frontend-app-api、core-compat-api、app-visualizer、dev-utils、frontend-test-utils等包随frontend-plugin-api@0.7.0-next.3的覆盖机制同步更新；
@backstage/plugin-api-docs@0.11.8-next.3与@backstage/plugin-catalog@1.22.0-next.3（变更6582799）：为所有表格新增tableOptions属性，API 表格额外支持title标题属性；
@backstage/cli@0.27.0-next.4：将processpolyfill 切换为require.resolve以提升兼容性（6d898d8），并将@module-federation/enhanced升级到 0.3.1（2ced236）；
@backstage/create-app@0.5.18-next.4（变更bfeba46）：新脚手架工程默认内置并启用权限（permission）配置。

6.2 后端与安全

@backstage/backend-defaults@0.4.2-next.3（变更81f930a）：使用格式化查询防止 SQL 注入风险；
@backstage/backend-plugin-api@0.8.0-next.3（变更ddde5fe）：修复依赖 multiton 服务的插件/模块无法获得正确类型的类型问题（该变更同时涉及backend-common的内部类型重构）。

6.3 Scaffolder 各模块

publish:bitbucketCloud动作新增初始化仓库时可设置初始提交信息的能力（d57967c）；
github:repo:create与github:pages动作补充了示例并改进测试用例（6d4cb97、cd203f1）；
publish:azure动作补充示例并更新测试（187f583）；
gitlab:issues:create动作新增测试用例（da97131）；
Scaffolder Runs 页面加载时标题不再显示 undefined（d18f4eb）；
EntityPicker 下拉增加额外高度，当选项少于 10 个时移除滚动条，让"还有更多选项"的提示更清晰（47ed51b）。

6.4 TechDocs

TechDocsReaderPage 样式支持更细粒度的主题覆盖，主题变量不再影响 Backstage 其他区域（27794d1）；
TechDocs 重定向功能在跳转前增加用户通知提示（8543e72）；
修复嵌套文档的编辑 URL 生成问题（5cedd9f）；
techdocs-backend更新配置 schema 使其与实际行为一致（a16632c）。

七、升级要点与依赖关系

升级工具：本版本变更日志顶部附带了官方 Upgrade Helper 入口（?to=1.30.0-next.4），可用于评估当前应用各包与目标版本的差距；
版本语义：各包均遵循语义化版本，Minor 变更表示向后兼容的新增能力（如上述五个包的next.x版本），Patch 变更表示缺陷修复与依赖升级；升级时建议按依赖关系自底向上（catalog-model→frontend-plugin-api→ 各插件）更新；
依赖传导：@backstage/catalog-model@1.6.0-next.0是本次更新的核心依赖节点，几乎所有前端插件（scaffolder、catalog、techdocs、search、home 等）均因其而重新发版；backend-plugin-api@0.8.0-next.3则是后端侧的核心依赖节点，auth、catalog-backend、search-backend、events、signals、permission 等后端包全部随之更新；
示例应用：仓库内的example-app、example-app-next、example-backend、example-backend-legacy以及e2e-test均同步升级到对应 next 版本（见 docs/releases/v1.30.0-next.4-changelog.md 末尾的 example-app 章节），可作为升级后各插件搭配的参考清单。

结语

v1.30.0-next.4是一份以"前端插件系统覆盖能力完善"为主线的预发布版本：withOverrides、getExtension、Extension.override与.make/.makeWithOverrides拆分共同构成了新前端系统"在不改源码的前提下定制插件"的完整工具链；与此同时，Catalog 的spec.type扩展、Cloudflare Access 自定义头、通知默认已读与无用户目录支持，则为实际部署提供了更灵活的选项。若你的应用大量使用了旧版 Extension Creator 或依赖 Scaffolder picker 的旧展示逻辑，升级时应重点回归上述模块。

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

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

Backstage v1.30.0-next.4 版本解读：前端插件覆盖机制、Catalog 实体扩展与通知系统增强