Backstage v1.47.0-next.0 变更解读BUI 主题令牌重命名、SearchField 折叠修复与 OIDC 自定义授权参数【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文基于 Backstage 仓库内 docs/releases/v1.47.0-next.0-changelog.md 整理。v1.47.0-next.0 是 Backstage v1.47.0 系列的第一个next预发布版本覆盖backstage/ui、backstage/backend-defaults、backstage/cli、OIDC 认证模块等二十余个包的变更。读完本文你将掌握本次预发布中唯一一项破坏性变更CSS 变量--bui-bg重命名的迁移方法、SearchField 折叠交互的修复细节、OIDC Provider 新增的startUrlSearchParams配置用法以及 CLI 对 ES2023/ES2024 语法的支持情况并了解如何借助仓库源码核验这些变更的实际行为。一、版本总览这是一次什么样的预发布v1.47.0-next.0是 Backstage 采用next预发布 正式发布双轨节奏下的一个早期候选版本。从变更清单看本次版本的整体特征是仅一项破坏性变更backstage/ui0.11.0-next.0将 CSS 变量--bui-bg重命名为--bui-bg-surface-0多项行为修复SearchField 折叠态修复、暗色模式应用背景色修复、后端健康检查关闭响应中的拼写错误修复一项新配置能力OIDC 认证 Provider 支持通过startUrlSearchParams注入自定义的授权起始 URL 查询参数大量依赖版本更新本次变更涉及的核心依赖为backstage/backend-plugin-api1.6.0、backstage/backend-app-api1.4.0、backstage/frontend-plugin-api0.13.2等绝大多数包为同步升级。由于是next预发布若想通过官方 Upgrade Helper 工具评估从当前版本升级到1.47.0-next.0的差异可在 Upgrade Helper 中指定目标版本1.47.0-next.0该工具由 Backstage 官方维护用于对比版本间依赖变化。生产环境建议等待正式版本发布后再执行升级。二、破坏性变更BUI 主题令牌--bui-bg重命名为--bui-bg-surface-02.1 变更内容backstage/ui0.11.0-next.0的 Minor Changes 中记录了本次版本唯一一项破坏性变更commit4ea1d15BREAKING: Renamed CSS variable--bui-bgto--bui-bg-surface-0for consistency.即如果你在自定义主题或组件样式中引用过--bui-bg变量升级后该变量将不再生效必须改为--bui-bg-surface-0。这一重命名的动机是保持一致性for consistency。从仓库中的设计令牌体系可以看出BUIBackstage UI的颜色变量已经形成了规范化的命名层级例如 packages/ui/src/css/tokens.css 中的背景类令牌全部采用--bui-bg-*前缀--bui-bg-app应用整体背景色浅色主题为#f5f5f5--bui-bg-neutral-1~--bui-bg-neutral-4中性层级背景如--bui-bg-neutral-1: var(--bui-white)--bui-bg-solid/--bui-bg-solid-hover/--bui-bg-solid-pressed/--bui-bg-solid-disabled实色背景及其交互状态--bui-bg-danger/--bui-bg-warning/--bui-bg-success/--bui-bg-info语义色背景。原有孤立的--bui-bg与这套--bui-bg-surface-*/--bui-bg-neutral-*体系不一致因此被并入--bui-bg-surface-0。仓库内 packages/ui/CHANGELOG.md 中同时保留了该重命名记录可交叉印证。2.2 迁移方法升级到backstage/ui0.11.0-next.0或包含它的正式版本后执行以下两步即可完成迁移全局搜索并替换所有自定义 CSS 中的var(--bui-bg)为var(--bui-bg-surface-0)检查依赖该令牌的插件尤其是使用 Backstage UI 主题令牌的组件。2.3 配套变更backstage/plugin-mui-to-bui与重命名同步backstage/plugin-mui-to-bui0.2.3-next.0在 Patch Changes 中记录了commite4a1180Updated tokens from--bui-bgto--bui-bg-surface-0plugin-mui-to-bui是 Backstage 提供的从 MUI 迁移到 BUI的辅助插件仓库内另有迁移脚本 scripts/mui-to-bui它内部生成的样式模板也同步更新了令牌引用。这意味着如果你已经使用或计划使用plugin-mui-to-bui做 MUI → BUI 迁移升级后生成的目标样式会直接产出--bui-bg-surface-0无需二次手工替换如果你维护的是自己手写的、参考旧模板复制过来的样式则需要按 2.2 节手动迁移。2.4 同版本 Patch暗色模式应用背景色修复backstage/ui0.11.0-next.0还包含一项与背景色直接相关的修复commit1880402Fixes app background color on dark mode.从 packages/ui/src/css/tokens.css 的令牌定义可以看到BUI 在浅色与暗色两套主题下分别声明了--bui-bg-app浅色主题为#f5f5f5暗色主题约 218 行起的暗色块为#333333。本次修复针对的就是暗色主题下应用背景色显示不正确的问题升级backstage/ui即可获得修复。三、交互修复SearchFieldstartCollapsed折叠态失效问题3.1 问题与修复内容backstage/ui0.11.0-next.0的 Patch Changes 中commitb4a4911修复了 SearchField 组件的startCollapsed属性不生效的问题。变更说明原文为Fixed SearchFieldstartCollapsedprop not working correctly in Backstage UI. The field now properly starts in a collapsed state, expands when clicked and focused, and collapses back when unfocused with no input. Also fixed CSS logic to work correctly in all layout contexts (flex row, flex column, and regular containers).即修复后的预期行为是初始时字段处于折叠态仅显示搜索图标点击 / 聚焦时展开输入框失焦且无输入内容时重新折叠折叠态的 CSS 逻辑在 flex row、flex column 以及普通容器三种布局场景下均能正确工作。3.2 源码层面的实现印证startCollapsed属性的定义位于 packages/ui/src/components/SearchField/types.tsstartCollapsed?: boolean与 packages/ui/src/components/SearchField/definition.ts默认值为false并声明为dataAttribute。核心折叠判定逻辑在 packages/ui/src/components/SearchField/SearchField.tsx 中const isCollapsed hasInputRef ? startCollapsed !hasValue !isFocused : startCollapsed !restProps.value !restProps.defaultValue !isFocused;可以看到折叠状态由三个条件共同决定startCollapsed开关是否开启当前输入框是否有值受控场景下检查value/defaultValue当前输入框是否聚焦。组件通过data-collapsed{isCollapsed}将折叠状态暴露给 CSS渲染在AriaSearchField根节点上由样式层根据该属性切换宽度/显示。修复同时覆盖了受控与非受控两种用法并调整了 CSS 使其不依赖特定布局上下文——这正是 changelog 中所说的all layout contexts。3.3 使用示例import { SearchField } from backstage/ui; // 默认展开 SearchField aria-labelSearch placeholderSearch... / // 默认折叠点击后展开失焦且无输入时自动收起 SearchField aria-labelSearch placeholderSearch... startCollapsed /升级到包含该修复的版本后若你此前遇到startCollapsed无效或折叠态样式错乱的问题无需改动代码即可获得修复。四、新配置能力OIDC Provider 支持startUrlSearchParams4.1 变更内容backstage/plugin-auth-backend-module-oidc-provider0.4.11-next.0新增了对自定义授权起始 URL 查询参数的支持commite54fcb2Added support for custom start URL search parameters (with the newstartUrlSearchParamsconfig property)该能力允许为 OIDC 授权端点authorize 端点的起始 URL 追加自定义查询参数例如向 IdP 传递租户标识、ui_locales、login_hint 等 OIDC 扩展参数。4.2 配置 Schema在 plugins/auth-backend-module-oidc-provider/config.d.ts 中startUrlSearchParams被定义为字符串键值对映射oidc?: { [authEnv: string]: { clientId: string; clientSecret: string; metadataUrl: string; callbackUrl?: string; tokenEndpointAuthMethod?: string; tokenSignedResponseAlg?: string; additionalScopes?: string | string[]; prompt?: string; timeout?: HumanDuration | string; startUrlSearchParams?: [string: string]; // ... }; };注意 OIDC Provider 支持按 authEnv认证环境拆分配置startUrlSearchParams位于每个环境的 provider 配置块内。4.3 配置示例在app-config.yaml中按如下方式启用auth: providers: oidc: development: clientId: ${AUTH_OIDC_CLIENT_ID} clientSecret: ${AUTH_OIDC_CLIENT_SECRET} metadataUrl: ${AUTH_OIDC_METADATA_URL} startUrlSearchParams: ui_locales: zh-CN login_hint: developer acr_values: urn:mace:incommon:iap:silver4.4 源码实现与边界约束参数的实际注入逻辑位于 plugins/auth-backend-module-oidc-provider/src/authenticator.tsinitialize阶段通过config.getOptional(startUrlSearchParams) || {}读取配置第 88–89 行并随initializedPrompt、promise一起作为上下文返回第 151 行start阶段构造授权 URL 时以展开自定义参数为基底再覆盖标准参数第 158–164 行// Merge the custom start URL params, but do not override the standard params (scope, state etc) const options: Recordstring, string { ...searchParams, scope: input.scope, state: input.state, nonce: crypto.randomBytes(16).toString(base64), }; const prompt initializedPrompt || none; if (prompt ! auto) { options.prompt prompt; } return helper.start(input, { ...options });关键约束有两层标准参数不可被覆盖scope、state、nonce由 Backstage 在自定义参数之后写入因此即使用户在配置中传入同名参数也会被标准值覆盖prompt则由initializedPrompt即配置项prompt优先决定。prompt默认值为none若配置了prompt且不为auto会显式写入授权 URL若未配置默认追加promptnone。4.5 测试用例验证对应行为在 plugins/auth-backend-module-oidc-provider/src/authenticator.test.ts 中有两组针对性测试passes custom start URL search parameters配置startUrlSearchParams: { foo: 1, bar: 2 }后断言授权 URL 中能解析出foo1、bar2does not override the core start URL search parameters with custom ones配置中恶意传入prompt、scope、state、nonce的自定义值断言最终授权 URL 中的这四个标准参数均不等于自定义值foo等自定义参数仍正常透传。这两组用例恰好把 4.4 节的边界约束固化为可回归验证的行为升级时无需担心自定义参数破坏 OIDC 授权流程的安全性。五、构建工具链CLI 支持 ES2023 / ES2024 语法backstage/cli0.35.2-next.0本次有两项 Patch 变更均围绕 SWC 转译器commit320c6a9Bumpswc/core以支持ES2023和ES2024commit9ee5996Bumpswc/core的最低要求版本以规避一个转译transpilationbug。含义解读Backstage CLI 使用 SWC 作为 JavaScript/TypeScript 的转译后端升级swc/core后插件与应用的代码可以放心使用ES2023如数组findLast/findLastIndex、toSorted/toReversed等与ES2024如Promise.withResolvers等的新特性CLI 的start、build命令在转译时不会再报语法错误9ee5996提高了swc/core的最小版本门槛主要目的是让所有使用 Backstage CLI 的用户统一避开某个已确认的转译缺陷属于防御性升级。对于使用 Backstage CLI 的插件/应用开发者升级backstage/cli后无需额外操作但如果你在package.json中显式锁定了旧版swc/core需要一并提升到满足 CLI 要求的最低版本。六、后端稳定性小修健康检查关闭响应拼写修复backstage/backend-defaults0.14.1-next.0的 Patch Changes 记录了一项不起眼但值得注意的修复commit7126bf2Fixed a spelling mistake in root health service shutdown response.即根健康检查服务root health service在关闭shutdown场景下返回的响应文本存在拼写错误本次已修正。虽然这只是文案层面的修复不会影响健康检查的语义但会体现在/health等端点的响应内容中依赖响应文本做断言或监控告警匹配的团队需要注意。与关闭shutdown机制相关的底层实现可参考 packages/backend-defaults/src/entrypoints/database/DatabaseManager.ts当提供了 root lifecycle 服务时DatabaseManager 会注册 shutdown hook第 73–77 行在shutdown()中依次关闭各数据库连接器对应测试见 packages/backend-defaults/src/entrypoints/database/DatabaseManager.test.ts。这从侧面说明 Backstage 后端在优雅关闭路径上是有完整生命周期管理的本次拼写修复正是这条路径上的收尾细节。七、内部重构OpenAPI 工具包的基础路径处理backstage/backend-openapi-utils0.6.5-next.0包含一项内部重构commit6678b78Internal update to use native feature from our request validation library for handling base path determination.即基础路径base path的判定逻辑改为复用请求校验库request validation library的原生能力不再由backend-openapi-utils自行实现。这是纯内部实现变更对外 API 与行为不变backstage/plugin-catalog-backend、backstage/plugin-scaffolder-backend、backstage/plugin-search-backend、backstage/plugin-events-backend等基于 OpenAPI 路由的后端插件均随此包同步升级见各插件 Patch 的依赖列表。八、依赖同步升级清单无行为变更本次预发布中以下包仅因上游依赖更新而同步发布新版本未包含独立的行为变更均为 Patch Changes包版本说明backstage/backend-dynamic-feature-service0.7.8-next.0依赖backend-defaults、backend-openapi-utils等升级backstage/backend-test-utils1.10.3-next.0测试工具包同步升级backstage/create-app0.7.8-next.0仅 Bump 版本跟随 CLIbackstage/dev-utils1.1.19-next.0跟随backstage/uitechdocs/cli1.10.4-next.0跟随backend-defaults与plugin-techdocs-nodebackstage/plugin-app-visualizer0.1.27-next.0跟随backstage/uibackstage/plugin-catalog-backend 及 AWS / GitLab / GitLab-org / incremental-ingestion / logs 模块3.3.1-next.0 等跟随 OpenAPI 工具包与 backend 核心backstage/plugin-devtools-backend0.5.13-next.0依赖同步backstage/plugin-events-backend0.5.10-next.0依赖同步backstage/plugin-mcp-actions-backend0.1.7-next.0依赖同步backstage/plugin-scaffolder-backend 及 cookiecutter / yeoman / node-test-utils 模块3.1.1-next.0 等跟随 backend 核心backstage/plugin-search-backend2.0.10-next.0依赖同步backstage/plugin-techdocs-backend2.1.4-next.0依赖同步backstage/plugin-user-settings-backend0.3.10-next.0依赖同步example-app / example-app-next / example-backend / e2e-test / techdocs-cli-embedded-app各 next.0仓库内置示例与 e2e 工程跟随升级这些包的升级对最终用户透明但如果你的应用直接依赖其中某个包例如自己装配后端时引用backend-defaults建议与本次发布保持一致避免版本碎片化。九、升级建议与注意事项重点关注破坏性变更唯一必须动手迁移的是--bui-bg→--bui-bg-surface-0。升级backstage/ui及backstage/plugin-mui-to-bui后先全局搜索--bui-bg的使用点确认无残留引用。OIDC 用户可按需启用新参数需要向 IdP 传递自定义 authorize 参数时在auth.providers.oidc.env.startUrlSearchParams下配置键值对注意scope、state、nonce、prompt四个标准参数不受该配置影响。SearchField 折叠态若旧版本上startCollapsed失效升级后即可生效无需改代码若你自行覆盖了 SearchField 的折叠样式请确认与data-collapsed属性配合的 CSS 在 flex 布局下仍正确。CLI 用户确保swc/core不低于 CLI 要求的最低版本以便正常转译 ES2023/ES2024 语法。预发布版本定位next.0是候选版本建议在测试环境先行验证上述变更再等待正式版发布仓库内 docs/releases 目录下保留了从 v1.0.0 至今的完整发布记录可作为版本演进参考。参考文件索引变更清单原文docs/releases/v1.47.0-next.0-changelog.mdBUI 设计令牌packages/ui/src/css/tokens.cssSearchField 实现与类型packages/ui/src/components/SearchField/SearchField.tsx、packages/ui/src/components/SearchField/types.tsOIDC Provider 实现、配置 Schema 与测试plugins/auth-backend-module-oidc-provider/src/authenticator.ts、plugins/auth-backend-module-oidc-provider/config.d.ts、plugins/auth-backend-module-oidc-provider/src/authenticator.test.ts后端 shutdown 机制packages/backend-defaults/src/entrypoints/database/DatabaseManager.tsMUI → BUI 迁移脚本scripts/mui-to-bui【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考