Backstage v1.52.0 版本发布详解：FrontendHostDiscovery 默认化、Catalog 性能优化与 BUI 语义化设计系统升级

Backstage v1.52.0 版本发布详解：FrontendHostDiscovery 默认化、Catalog 性能优化与 BUI 语义化设计系统升级

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

Backstage v1.52.0 是一次包含多个BREAKING 变更的重要版本，核心围绕"默认发现机制切换为FrontendHostDiscovery、彻底移除 immediate 模式 stitching、Backstage UI（BUI）异步集合组件与语义化色彩 token 体系上线"三大主线展开，同时为 Catalog 后端带来一批针对 PostgreSQL 的深度性能优化，并新增实验性@backstage/connections包。阅读本文你将掌握该版本所有破坏性变更的迁移步骤（ComboboxProps/SelectProps联合类型改造、CSS token 重命名对照、discovery.endpoints配置修正），理解/entities/by-query的totalItems控制与拆分查询原理，以及 Scaffolder 新增的 secrets 校验、Git push 重试与 GitHub GraphQL 回退等可靠性能力，从而安全、平滑地完成升级。

本仓库 docs/releases/v1.52.0-changelog.md 与 docs/releases/v1.52.0.md 为本文核心依据，文中涉及的源码与配置均可按相对路径在仓库中查阅。官方 Upgrade Helper 工具可协助按目标版本1.52.0规划升级步骤（也可参照仓库内 docs/getting-started/keeping-backstage-updated.md 的升级流程）。

版本速览与升级总览

v1.52.0 涉及的核心包版本与性质如下，升级前建议先对照确认自己项目依赖到的范围：

本版本不包含安全修复（Security Fixes 部分明确声明 "This release does not contain any security fixes"）。升级时请重点关注下面两个 Breaking 变更，因为它们直接影响现有配置与代码。

BREAKING：默认 Discovery API 切换为 FrontendHostDiscovery

@backstage/plugin-app@0.5.0将默认的 discovery API 实现从原有实现切换为FrontendHostDiscovery，这是本版本最重要的行为变化之一。切换后，前端将开始真正生效discovery.endpoints配置——包括字符串形式的target值。

原理：FrontendHostDiscovery 如何解析配置

在仓库中，FrontendHostDiscovery的实现位于 packages/core-app-api/src/apis/implementations/DiscoveryApi/FrontendHostDiscovery.ts。从源码可以看出其解析逻辑：

• 通过config.getOptionalConfigArray('discovery.endpoints')读取配置数组，逐项flatMap展开；
• 当target是对象时，取target.external作为浏览器可访问地址（e.getOptionalString('target.external')）；
• 当target是字符串时，直接作为目标 URL；
• 每个 endpoint 通过UrlPatternDiscovery.compile(target)编译，再按plugins数组映射为pluginId -> discovery的 Map；
• 未命中任何 endpoint 的插件，回退到backend.baseUrl + pathPattern，默认路径模式为/api/{{ pluginId }}；
• 查找时按endpoints.get(pluginId) ?? endpoints.get('*')依次匹配精确插件与通配符'*'（见 FrontendHostDiscovery.ts#L89-L95）。

配置格式：字符串 target 与对象 target

FrontendHostDiscovery的 docstring 给出了完整的discovery.endpoints配置示例，覆盖字符串与对象两种形式：

discovery: endpoints: - target: https://internal.example.com/internal-catalog plugins: [catalog] - target: https://internal.example.com/secure/api/{{pluginId}} plugins: [auth, permissions] - target: internal: https://internal.example.com/search external: https://example.com/search plugins: [search] - target: https://example.com/api/{{pluginId}} plugins: ['*']

迁移要求（重要）

由于前端开始生效discovery.endpoints，如果你目前在该配置中使用仅内部可达的字符串target，必须改为对象形式，并按以下规则修正：

1. 将内部 URL 移动到target.internal；
2. 省略target.external，或将其设置为浏览器可达的 URL；
3. 否则前端会被路由到内部 URL，导致浏览器访问失败。

判断要点：target.internal用于服务端/内部访问，target.external用于浏览器端。若某 endpoint 仅用于内部，就只写target.internal而不写target.external。

配套修复

同一版本中，FrontendHostDiscovery相关的修复还包括：core-components修复了 Header tab 链接未遵循路由basename的问题（commit b06b3c7），确保多 base path 部署下前端导航行为正确。

BREAKING：Catalog 移除 immediate 模式 stitching

@backstage/plugin-catalog-backend@3.8.0移除了catalog.stitchingStrategy.mode: 'immediate'配置。该设置在 v1.51.0 中已标记废弃，本版本正式移除。

行为变化与兼容处理

• 所有 stitching 现在统一使用deferred 模式：实体通过 worker 队列异步处理；
• 如果配置中仍包含catalog.stitchingStrategy.mode: 'immediate'，该值会被忽略并产生一条 deprecation 警告，不会导致启动失败；
• pollingInterval与stitchTimeout设置继续按原语义生效，无需改动。

底层修复：stitch 队列的并发安全

与 stitching 移除配套的是若干队列语义修复，保证 deferred 模式在并发下的正确性：

• 修复竞态条件（commit 774d698）：SELECT FOR UPDATE SKIP LOCKED行锁在时间戳更新前被释放，导致多个 worker 认领同一行。现在 MySQL/PostgreSQL 上 select 与 update 在同一事务内执行；
• 避免同一实体的重叠 stitch（commit 0b8b677）：stitch 进行中新到达的请求只更新 ticket 而不更新 timestamp，避免打断进行中的 worker；worker 完成后若检测到待重 stitch，队列条目立即进入可认领状态，无需等待超时。

Backstage UI（BUI）0.16.0：异步集合组件与语义化色彩体系

@backstage/ui@0.16.0是本版本中改动面最大的前端包，同时包含BREAKING 变更、新组件与主题 token 体系升级。此外@backstage/eslint-plugin@0.3.1新增了配套的 lint 规则。

Combobox 与 Select 支持异步集合

Combobox和Select现在都支持：

• 异步集合（async collections）与增量加载（incremental loading）；
• 客户端搜索与服务器端搜索；
• 富文本/自定义选项渲染。

加载占位符通过公共 CSS 类暴露：Combobox为.bui-ComboboxLoading与.bui-ComboboxLoadingRow，Select为.bui-SelectLoading与.bui-SelectLoadingRow；过期但仍显示的旧结果通过.bui-ComboboxList/.bui-SelectList上的data-stale属性标记。

滚动加载行为也得到修正（commit 350407d）：Combobox/Select弹层现在随滚动逐页加载，而非一次性加载全部页面。Combobox使用.bui-PopoverContent作为滚动容器，所有Select变体统一使用新的.bui-SelectResults结果容器；可搜索Select保持搜索框固定、结果区滚动，并通过新的公共类.bui-SelectContent与.bui-SelectResults暴露布局以便主题定制。

BREAKING：Props 接口变为联合类型

ComboboxProps与SelectProps的公共接口现在均为联合类型。升级时必须执行的迁移：把所有extends这些接口的 interface 改为类型交叉（type intersection）。

以Combobox为例：

- interface MyComboboxProps extends ComboboxProps { - trackingId: string; - } + type MyComboboxProps = ComboboxProps & { + trackingId: string; + };

Select的迁移方式完全一致。此外，Select弹层列表内容不再是.bui-SelectPopover的直接子元素——其内容现在被包装在标准的 BUI Popover 内容结构中（.bui-Box.bui-PopoverContent），原有.bui-Popover.bui-SelectPopover根类保持不变。因此，依赖"列表内容作为.bui-SelectPopover直接子元素"的 CSS 选择器需要更新。

可选迁移：从废弃 API 切换到新写法

以下迁移是可选的（旧写法仍作为兼容路径保留），但推荐新代码直接采用新写法：

1. 选项标识：优先使用id而非value

普通数组选项仍支持value，但新选项内容字段与异步选项源要求使用id：

- <Combobox inputValue={query} onInputChange={setQuery} /> + <Combobox search={{ inputValue: query, onInputChange: setQuery }} />

2. 输入状态与自定义过滤迁入嵌套search配置

- <Select searchable searchPlaceholder="Search owners" /> + <Select search={{ placeholder: 'Search owners' }} />

对于普通数组options，顶层 input state props 仍受支持（废弃兼容路径）。

新组件：NumberField

新增NumberField组件（commit b33bb24），用于数值输入，支持：

• min/max范围约束；
• step步进；
• 键盘递增/递减。

语义化色彩 Token 家族与迁移对照表

本版本引入一组新的语义化 color token 家族：Accent、Announcement、Warning、Negative、Positive，每个家族在明暗主题下都提供一致的 background、foreground、border token；同时新增灰度标尺--bui-gray-1至--bui-gray-11与更新后的 foreground tokens。旧 token 保留以兼容旧代码，但已废弃，将在未来版本移除。

配套的@backstage/eslint-plugin@0.3.1新增@backstage/no-deprecated-bui-tokenslint 规则（commit 5d80f77），集成在recommended配置中——使用plugin:@backstage/recommended的插件作者会自动收到废弃 token 的警告。注意：该规则只覆盖 JS/TS 文件（含 CSS-in-JS 与模板字符串），普通 CSS 与 CSS module 文件不在 ESLint 覆盖范围内。

以下是官方迁移对照表，请按表逐项替换：

Neutral backgrounds

中性背景 token 名称保持不变（--bui-bg-app、--bui-bg-neutral-1~--bui-bg-neutral-4），但明暗主题下更新为新的实色值，无需重命名。其-hover、-pressed、-disabled交互变体已被废弃，应删除。

Foreground

Accent

Positive

Negative

Warning

Announcement

其他 BUI 组件修复

• 深色主题中性背景 token 更新，提升中性表面之间的对比度（commit 3d6c2e4）；
• Table组件修复 Firefox 下无法撑满容器宽度的问题：overflow样式移到外层 wrapper 而非<table>本身（commit c86efcd）；
• Skeleton组件背景感知，自动调整颜色以在父级中性表面上保持可见对比度（commit adf94f5）；
• Switch根据父容器背景适配轨道与滑块颜色，选中时使用 accent token 家族（commit 14a101f）；
• 修复 tab 内容宽度动态变化时 tab 指示器位置不更新（commit 66c4e55）；
• 修复Combobox客户端搜索搭配普通 options 时的崩溃（commit e989f95）；
• 修复Header面包屑排版在不同样式加载顺序下的不一致（commit 1f709a3）。

新实验包：@backstage/connections 0.1.0

本版本新增@backstage/connections@0.1.0，标记为实验性，仅用于实验用途。从变更日志的定义看，Connection是一段配置，用于存储外部主机地址以及与该主机认证所需的凭据：

• 一个 Connection 可被多个插件消费，从而减少重复配置；
• Connection 可包含多种认证方式（auth methods），且可被限制到指定插件/模块；
• 新增title字段（commit 95688f6），提供人类可读的展示名：未显式配置时默认取 provider 名（如 "GitHub"），多个同类型 Connection 共享同一 provider 时则包含主机名（如 "GitHub (ghe.acme.com)"）。

其长期目标是逐步取代现有的 integrations 概念，并支持更广泛的系统类型。相关设计提案（BEP-0014）完整内容见仓库 beps/0014-connection-service/README.md。仓库中还包含配套的示例实现：plugins/connections-example-backend 与 plugins/connections-example-backend-module-gitlab，可用于实验性参考。

Catalog：totalItems 控制与列表/计数查询拆分

新参数：totalItems: 'include' | 'exclude'

/entities/by-query端点现在接受totalItems参数（'include'或'exclude'，默认'include'），控制响应中的totalItems计数是否计算：

• 调用方不需要计数时传'exclude'可完全跳过计数——对仅"装饰性"展示计数的 cursor 分页 UI 尤其有用；
• 该参数的合法值列表是前向兼容的：未来可增加新模式（如近似计数）而不破坏现有调用方。

对应的客户端 API 同步更新：@backstage/catalog-client@1.16.0的CatalogApi.queryEntities在初始请求中接受相同的totalItems选项。源码证据见 packages/catalog-client/src/types/api.ts#L491-L499，其类型注释明确：'exclude'时响应totalItems为0，适用于仅装饰性展示计数的 cursor 分页 UI。

同时，内部QueryEntitiesInitialRequest.skipTotalItems选项被替换为totalItems: 'include' | 'exclude'。由于skipTotalItems从未暴露为 REST 参数，这只是影响直接调用EntitiesCatalog.queryEntities的 TypeScript 层面变更。

另外两个相关修正：排序字段键在与search.key比较前会先小写化，修复 camelCase 字段名导致的静默不匹配；NULLS LAST排序子句被移除——NULL 排序值已被WHERE子句排除，无需再显式处理。

前端：列表与计数拆分并行请求

@backstage/plugin-catalog-react@3.1.0的实体列表 provider 现在在使用 cursor 或 offset 分页时，将列表查询与总数查询拆为两个并行的独立请求：

• 列表查询使用totalItems: 'exclude'跳过昂贵的计数计算，表格立即填充；
• 计数异步到达后更新标题；
• 新增totalItemsLoading字段（EntityListContextProps），让消费者区分过期计数与新鲜计数；
• Catalog 表格在筛选变化与翻页时保留旧行可见，不再用 spinner 替换整个表格主体；仅在首次加载无数据时才显示全表 spinner；
• 计数刷新期间标题中的实体数变暗，行加载时标题旁显示小 spinner。

相关源码见 plugins/catalog-react/src/hooks/useEntityListProvider.tsx，其中totalItemsLoading状态（L124）、refresh/triggerRefresh机制（L132、L261、L505）均清晰可见。

新 hook 能力：useEntityList 的 refresh

useEntityListhook 新增refresh函数（commit 5dd532d），允许消费者以编程方式触发实体列表数据刷新，直接配合上述拆分查询使用。

新组件：CatalogExportButton

@backstage/plugin-catalog@2.0.6新增CatalogExportButton组件（commit 82cf16f），为CatalogIndexPage提供CSV 与 JSON 导出能力。

Catalog 后端：PostgreSQL 深度性能优化

@backstage/plugin-catalog-backend@3.8.0本轮性能优化的核心目标是修复大目录下查询计划器误判导致的性能退化，全部针对 PostgreSQL，要点如下：

1. 拆分 list 与 count 查询（commit 4829e89）：原实现使用多引用 CTE，filteredCTE 被引用两次时 PostgreSQL 拒绝内联，导致必须物化完整过滤集后再应用LIMIT。拆分后 list CTE 只被引用一次，计划器可在LIMIT处短路，首页在毫秒级返回；独立的 count 查询还修复了一个既有 bug——多值排序字段（如 tags）实体会被重复计数（3 个 tag 计 3 次），新 count 使用EXISTS按不同实体计数，使totalItems与 cursor 分页实际可达实体数一致；
2. 扩展多列统计（commit 39c5fbb）：在search表(key, value)上增加多列统计（仅 PostgreSQL），修复复合筛选查询的行数估计错误。此前计划器可能物化并排序数千行而非使用 LIMIT 短路索引扫描，导致多筛选条件下目录列表视图慢 10-40 倍；
3. 自动 vacuum 阈值调优（commit 24775dc）：对search、final_entities、relations、refresh_state_references表调优 PostgreSQL 自动 vacuum 阈值，并修复search表entity_id的列统计，防止维护滞后时计划器退化为顺序扫描；
4. 移除冗余索引（commit 9698738）：删除search_entity_id_idx，该索引与(entity_id, key, value)覆盖唯一索引冗余，且会导致多排序字段目录列表查询选择低效扫描路径，在大目录上性能严重退化；
5. entitiesBatch 查询优化（commit ccfa4f1）：PostgreSQL 上改用= ANY(array)而非WHERE IN ($1, $2, ...)，生成单一稳定查询计划，避免多达 200 个不同计划污染计划缓存；PostgreSQL 上批量不再必要，所有实体引用在单次查询中获取；
6. stitch 队列竞态与重叠修复（commit 774d698、0b8b677）：详见上文 stitching 部分；
7. 权限规则大小写不敏感（commit 750b310）：HAS_LABEL与HAS_ANNOTATION权限规则现在不区分大小写。

Scaffolder：secrets schema、v2 invoke 端点与可靠性增强

Actions secrets schema 与 v2 invoke 端点

@backstage/backend-plugin-api@1.9.2现在允许 Action 声明独立的 Zod secrets schema（与 input schema 分离），使界面层可以独立于工具参数收集敏感凭据：

• ActionsRegistryActionOptions与ActionsRegistryActionContext新增可选secretsschema 支持；
• ActionsServiceAction元数据与ActionsService.invoke()参数新增可选secrets字段；
• @backstage/backend-defaults@0.17.3新增v2 invoke 端点/.backstage/actions/v2/actions/:id/invoke，接受包裹格式{ input, secrets }并做 secrets 校验；v1 端点保持不变以向后兼容；
• DefaultActionsService改用 v2 端点；DefaultActionsRegistryService在 actions list 响应中暴露 secrets schema，并在调用时校验 secrets；
• @backstage/backend-test-utils@1.11.4的MockActionsRegistry同步支持：按声明的 schema 校验 secrets、对必需 secrets 缺失的 action 拒绝调用、并将 secrets 转发给 action handler。

dry-run 中恢复用户提供的 task secrets

@backstage/plugin-scaffolder-backend@4.0.1修复了上一轮安全修复过度删除的问题（commit 063fc34）：之前的修复在 dry-run 中同时剥离了请求体传入的 task secrets，破坏了依赖用户提供 secrets 的集成测试。现在仅服务器配置的环境 secrets 在 dry-run 中保持剥离，调用方提供的 task secrets 恢复转发给 actions。

Git push 重试与 GitHub GraphQL 回退

• @backstage/plugin-scaffolder-node@0.13.4为Git.push()增加指数退避重试（commit 3d0ba59）：创建仓库后立即 push（如publish:github）可能遇到仓库尚未完全就绪的瞬时失败，push 现在最多重试 5 次并递增延迟；认证与权限错误（401、403）立即失败不重试；
• @backstage/plugin-scaffolder-backend-module-github@0.9.10为publish:github与github:repo:push增加GitHub GraphQL API 回退（commit 464ebc2）：git push 遇到连接级错误（ECONNRESET或ECONNREFUSED，同时检查error.code与error.cause.code）时改用 GraphQL 重试。原因是 git smart HTTP 协议在 POST 中发送二进制 pack 数据，可能被做深度包检测的网络代理拦截；GraphQL 回退使用标准 JSON 请求，不受影响。

其他 Scaffolder 相关改进

• @backstage/plugin-scaffolder@1.38.0为RepoOwnerPicker扩展了GitLab 自定义变体（commit 3e5acb5）；
• @backstage/cli-module-new@0.1.4新增scaffolder-field-extension-module模板（commit 4014819），可通过backstage-cli new快速脚手架自定义 Scaffolder 表单字段扩展；
• 移除多个包的json-schema运行时依赖（仅保留import type类型引用，commit 02c4e8a）。

前端系统、CLI 与测试工具更新

create-app：Yarn 4.13 与供应链攻击防护

@backstage/create-app@0.8.4新脚手架的应用改用Yarn 4.13.0（原 4.4.1），并默认启用 Yarn 的npmMinimalAgeGate: 3d设置——拒绝安装发布不足三天的 npm 包，作为供应链攻击防御；Backstage 自身包通过npmPreapprovedPackages: ['@backstage/*']豁免，确保新发布版本可即时安装。现有应用不受影响；如需手动启用，可在自己的.yarnrc.yml中添加这两个设置并升级 Yarn 至 4.13 及以上。

懒加载 core-components 依赖

@backstage/core-components@0.18.11将react-syntax-highlighter与@dagrejs/dagre改为懒加载（commit c161e1c），不再通过 barrel export 被急切拉入，使从@backstage/core-components导入的前期模块开销减少约 10 MB，公共 API 不变。

测试工具：renderInTestApp 的 mountPath

@backstage/frontend-test-utils@0.6.1的renderInTestApp新增mountPath选项（commit 62dd4fc），控制测试元素渲染的路由路径模式；设置后元素被包在指定 path 的<Route>中，使useParams()能从 URL 提取路由参数，可配合initialRouteEntries设置匹配的具体 URL。适用于测试依赖 URL 参数的页面组件（如使用useRouteRefParams的实体页面）。

CLI 改进

• @backstage/cli@0.36.3改进了 CLI module 命令冲突校验（commit b521571），包括父命令与嵌套命令路径之间的冲突；
• @backstage/cli-node@0.3.3新增runCli，可从一组固定、直接导入的 CLI modules 创建可执行 CLI 包，并校验冲突命令路径；单模块的runCliModule辅助函数现已废弃；
• 各cli-module-*的--help输出现在显示生成的 usage 行（列出可用 flags 与位置参数）；
• cli-module-build抑制@protobufjs/inquire的误报 "Critical dependency" 警告，并升级embedded-postgres至 18.3.0-beta.17。

其他前端/后端修复与增强

• toastApi 兼容（commit 74ed625）：app-defaults为旧前端系统提供 toastApi，修复旧系统下的'No implementation available for apiRef{core.toast}'错误；
• 动态后端插件加载回退（commit 7005478）：alphapackage.json存在但不提供插件入口时，回退到主包导出加载——此前仅导出辅助 API（如权限）的插件即使主导出有效也可能加载失败；
• 任务 worker 重试循环尊重 abort signal（commit 89a95ca）：遇到意外错误时不再无限重试，可优雅关闭；
• 内置限流器修复（commit def82d4）：启用backend.rateLimit时不再抛出校验错误，请求按express-rate-limit的地址归一化辅助函数分组，IPv6 客户端按地址块而非单个地址分组；
• URL-safe base64 会话 token 解码（commit 8add9b9）：修复代理登录页读取 URL-safe base64 编码的会话 token 失败；
• autologout 修复（commit dbe93a7）：关闭所有标签页时自动登出不再失效；
• Azure 相关修正：AzureBlobStorageIntegration拼写修正（旧拼写AzureBlobStorageIntergation保留为别名），AzureBlobStorageUrlReader接受可选createContainerClient依赖便于测试；
• GitLab URL reader：修复获取仓库 archive tree 的问题（commit 34f21c3）；
• SidebarSubmenuItem：行高从 1 修正为 1.5，修复文本裁剪（commit f35372d）；
• TableFiltersClassKey：新增正确拼写的'header'字面量，废弃拼错的'heder'（生成的旧 CSS 类保留兼容）；
• toast 文本可选：Toast 文本内容可被选中（commit 33d03ed）；
• infinispan 升级：从^0.12.0升级至^0.13.0，修复已知漏洞；
• events bus 请求体上限：提升至 5 MB 以支持更大事件负载（commit f4342b9）。

各集成模块更新

• Bitbucket Server（commit 9e2ff8c）：catalog-backend-module-bitbucket-server新增 SCM 事件翻译层，订阅 Bitbucket Server webhook 事件并翻译为通用 catalog SCM 事件，实现仓库 push/rename 时的即时目录重处理；analyzeBitbucketServerWebhookEvent函数从 alpha 入口导出供自定义集成使用；
• Microsoft Graph：修复user.select设为空数组导致所有用户被丢弃的问题（恢复默认字段集）；回退 v1.51.0 引入的服务端accountEnabled eq true基础过滤（该过滤破坏了userGroupMember路径，因组成员端点不支持该属性上的$filter），禁用用户在/users与组成员两条路径上均改为客户端过滤；
• OpenAPI/AsyncAPI（commit cf4b34b）：修复相对$ref解析，使用 ref parser 的原始引用字符串与父文档 URL，而非相对进程工作目录计算路径，修复跨目录 ref（如./../../common/specs/common.yaml）与深度 > 1 的嵌套 ref；
• Kubernetes：移除误注册到/kubernetes的默认独立页面（commit 07bd0b4）；KubernetesFetcher按集群池化 HTTPS agents（commit c4f935b）；
• MCP actions backend（commit ed1be73）：tools/list响应时逐个 action 校验 MCP tool schema，不合规的 action 记录警告并跳过，不再让整个响应失败；
• notifications backend（commit ac410b1）：内部路由迁移为基于插件 OpenAPI 规范生成，HTTP API 不变；
• TechDocs：补齐插件组件 i18n（搜索、表格、首页、Reader、错误消息与导航标签），并从 alpha 入口导出techdocsTranslationRef（commit 460c597）；
• OAuth2 Proxy provider（commit 9822a2a）：新增forwardedPreferredUsernameMatchingUserEntityName登录解析器；
• 增量摄取（commit e846874）：ingestions.last_error列类型调整，移除 255 字符限制；
• 权限规则：HAS_LABEL/HAS_ANNOTATION大小写不敏感；
• app-backend（commit ca450be）：新增app.disablePublicEntryPoint配置选项，设为true时跳过向未认证用户提供公共登录入口（即使应用打包了index-public-experimental入口）。

升级路径建议

1. 优先处理两个 Breaking 变更：检查app-config.yaml中的discovery.endpoints（必要时改为对象形式 +target.internal），以及catalog.stitchingStrategy.mode（如为immediate直接移除或改为 deferred 相关设置）；
2. 处理 BUI 类型与 token 迁移：将extends ComboboxProps/SelectProps的 interface 改为 type intersection，按上文对照表替换废弃 CSS token，并启用@backstage/no-deprecated-bui-tokenslint 规则辅助排查；
3. 关注 PostgreSQL 目录性能优化：这些优化是自动生效的（含新迁移），大目录部署可重点验证多筛选条件下的目录列表查询；
4. 测试工具与 CLI：如需测试依赖 URL 参数的页面，使用renderInTestApp的mountPath新选项。

完整升级指引可参照仓库 docs/getting-started/keeping-backstage-updated.md 与 docs/overview/versioning-policy.md。本版本的完整包级变更明细（含全部依赖更新）见 docs/releases/v1.52.0-changelog.md，版本亮点综述见 docs/releases/v1.52.0.md。

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