2026/9/12 12:30:55
FEATURED · 精选文章 
Backstage v1.10.0-next.2 变更深度解读Scaffolder 包重构、后端根路由服务与前端新能力【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇文章围绕 Backstage 开源仓库 docs/releases/v1.10.0-next.2-changelog.md 中记录的 v1.10.0-next.2 预发布版本展开逐项剖析该版本中 Scaffolder 生态的包级重构、新后端系统中rootHttpRouterServiceRef的引入、应用级 Feature Flags、搜索空状态定制、ADR 插件向 UrlReaders 的迁移等关键变化。读完本文你将掌握该版本涉及的核心 API 迁移路径、破坏性变更的应对方案以及若干新特性的具体用法可直接用于升级排查与新功能开发。说明本文基于仓库中记录的next预发布版本变更日志整理所有 API 签名、命令与行为均以仓库当前内容为准。-next.x表示正式发布前的迭代版本接口在后续版本中可能继续调整。一、版本全景一次覆盖前后端与 CLI 的大范围迭代v1.10.0-next.2 是 Backstage v1.10.0 正式发布前的第二个迭代版本变更范围横跨前端核心包backstage/app-defaults、backstage/core-app-api、backstage/core-plugin-api同步引入“应用级 Feature Flags”能力后端系统new backend systembackstage/backend-app-api、backstage/backend-plugin-api、backstage/backend-common完成一批服务与类型的迁移重构其中包含BREAKING变更Scaffolder 生态新包backstage/plugin-scaffolder-react1.0.0-next.0诞生从backstage/plugin-scaffolder收编了大量公共类型、组件、Hooks 与 API 引用同时为 Actions 页面引入 Markdown 描述与示例 YAML搜索与雷达backstage/plugin-search-react支持自定义空结果组件backstage/plugin-tech-radar增加图例高亮与悬停气泡ADR 插件前端与后端同时重构全面改用 UrlReaders 读取站点内容CLI 工具techdocs/cli的serve命令新增自定义预览应用入口与端口参数。从仓库依赖关系看example-app0.2.79-next.2与example-backend0.2.79-next.2也在本版本中同步升级是观察上述变化落地效果的最佳参照。二、Scaffolder 生态重构plugin-scaffolder-react 包诞生2.1 新包定位与迁移背景本版本最重要的一件事是新增了backstage/plugin-scaffolder-react1.0.0-next.0。其Major Changes明确指出将backstage/plugin-scaffolder中常用的类型、组件、Hooks 以及scaffolderApiRef重新安置到该新包中以便所有需要与 Scaffolder 交互的前端代码能够轻松复用。从仓库源码可以印证这一迁移结果scaffolderApiRef定义于 plugins/scaffolder-react/src/api/ref.ts通过createApiRefScaffolderApi创建createScaffolderFieldExtension实现于 plugins/scaffolder-react/src/extensions/createScaffolderFieldExtension.tsx并由 plugins/scaffolder-react/src/extensions/index.ts 统一导出useCustomFieldExtensions、useCustomLayouts等 Hook 集中在 plugins/scaffolder-react/src/hooks/index.ts。2.2 弃用导出清单迁移指引backstage/plugin-scaffolder1.10.0-next.2对本版本开始弃用以下导出要求调用方改从backstage/plugin-scaffolder-react导入createScaffolderFieldExtension ScaffolderFieldExtensions useTemplateSecrets scaffolderApiRef ScaffolderApi ScaffolderUseTemplateSecrets TemplateParameterSchema CustomFieldExtensionSchema CustomFieldValidator FieldExtensionOptions FieldExtensionComponentProps FieldExtensionComponent ListActionsResponse LogEvent ScaffolderDryRunOptions ScaffolderDryRunResponse ScaffolderGetIntegrationsListOptions ScaffolderGetIntegrationsListResponse ScaffolderOutputlink ScaffolderScaffoldOptions ScaffolderScaffoldResponse ScaffolderStreamLogsOptions ScaffolderTask ScaffolderTaskOutput ScaffolderTaskStatus同时rootRouteRef导出也被弃用应改用scaffolderPlugin.routes.root。如果你正在使用这些符号升级时只需替换 import 语句的来源包符号名称保持不变因此迁移成本较低。2.3/alpha类型迁移原backstage/plugin-scaffolder中的/alpha类型被移除并迁移到backstage/plugin-scaffolder-react/alphacreateNextScaffolderFieldExtension FormProps NextCustomFieldValidator NextFieldExtensionComponentProps NextFieldExtensionOptions这意味着一批面向“下一代表单扩展”的实验性 API 有了更合适的归属包后续扩展 Scaffolder 自定义字段时应从新位置导入。2.4 打包内补丁Actions 页面内容增强backstage/plugin-scaffolder同步获得三项体验增强使用MarkdownContent组件渲染 action 描述使 Action 文档页能够展示更丰富的富文本内容在 Scaffolder Actions 文档页展示 action 的示例 YAML将children显式声明为可选 props以适配 React 18 的 Props 类型要求backstage/plugin-techdocs-react也做了同样的调整。三、Scaffolder 后端createTemplateAction 支持 examples 示例3.1 新能力动作示例backstage/plugin-scaffolder-backend1.10.0-next.2为createTemplateAction增加了examples选项。仓库源码 plugins/scaffolder-node/src/actions/createTemplateAction.ts 中examples?: TemplateExample[]其类型定义为{ description: string; example: string }[]见 plugins/scaffolder-node/src/actions/types.ts。定义一个带示例的 action 如下const actionExamples [ { description: Example 1, example: yaml.stringify({ steps: [ { action: test:action, id: test, input: { input1: value, }, }, ], }), }, ]; export function createTestAction() { return createTemplateAction({ id: test:action, examples: [ { description: Example 1, examples: actionExamples, }, ], // ...schema、handler 等其余配置 }); }3.2 通过 API 读取示例示例注册后可经 Scaffolder 的 actions API 查询默认后端地址为curl http://localhost:7007/api/scaffolder/v2/actions返回 JSON 中会包含examples与schema字段[ { id: test:action, examples: [ { description: Example 1, example: steps:\n - action: test:action\n id: test\n input:\n input1: value\n } ], schema: { input: { type: object, properties: { input1: { title: Input 1, type: string } } } } } ]仓库测试 plugins/scaffolder-backend/src/actions/createListScaffolderActionsAction.test.ts 验证了该行为action 列表会携带examples数组并且能正确处理“没有描述、schema 或示例”的 action。注意示例内容是由createTemplateAction注册的模板参数 schema 推导而来input1的标题Input 1与类型string正是 schema 中properties.input1的映射结果。四、后端系统演进根 HTTP 路由服务与 BREAKING 变更4.1 新增 RootHttpRouterServicebackstage/backend-plugin-api0.3.0-next.1新增rootHttpRouterServiceRef与RootHttpRouterService接口。仓库源码 packages/backend-plugin-api/src/services/definitions/RootHttpRouterService.ts 中的接口定义非常简洁export interface RootHttpRouterService { /** Registers a handler at the root of the backend router. * The path is required and may not be empty. */ use(path: string, handler: Handler): void; }该服务注册在coreServices中见 packages/backend-plugin-api/src/services/definitions/coreServices.ts用于在 Backend 路由的根层级注册处理器适合承载健康检查、根路径跳转等全局逻辑。同时backstage/backend-defaults0.1.5-next.1默认安装了这个新的根 HTTP 路由服务example-backend-next也随版本同步升级使用。4.2 httpRouterFactory 的破坏性变更backstage/backend-app-api0.3.0-next.1对插件级路由工厂做出BREAKING调整httpRouterFactory现在接受getPath选项不再接受indexPlugin若要设置自定义 index 路径应改用新的rootHttpRouterFactory并配置indexPath。从源码结构看rootHttpRouterFactory与httpRouterFactory形成了“根路由 / 插件路由”的分层根级 index 跳转与插件级路由挂载解耦便于在根层统一管理入口。4.3 loggerToWinstonLogger 迁移本版本将loggerToWinstonLogger从backstage/backend-plugin-api迁移至backstage/backend-common。仓库中大量模块plugin-app-backend、plugin-catalog-backend、各 catalog 后端模块、events 后端模块等均切换了导入来源。backstage/backend-common0.18.0-next.1同步把对 winstonLogger类型的依赖替换为backend-plugin-api中的LoggerService——由于LoggerService是Logger接口的子集这不构成破坏性变更。4.4 服务实例化与校验强化backend-app-api与backend-plugin-api还包含多项健壮性改进新增ServiceFactoryOrFunction类型用于同时接受ServiceFactory或() ServiceFactory两种形式createSpecializedBackend在传入重复服务实现时抛出错误尝试覆盖 plugin metadata 服务时将抛出错误backend-defaults确保自定义服务实现能够替换默认实现插件日志标签从pluginId改为pluginbackstage/backend-test-utils的startTestBackend现在默认包含所有核心服务的默认实现方便测试新后端系统插件。backstage/backend-common的createRootLogger也支持覆盖默认的service日志标签同时将better-sqlite3升级到^8.0.0。若你的packages/backend/package.json中锁定了旧版本可按backstage/create-app的提示升级- better-sqlite3: ^7.5.0, better-sqlite3: ^8.0.0,五、前端核心应用级 Feature Flags5.1 应用层面定义特性开关backstage/app-defaults、backstage/core-app-api、backstage/core-plugin-api三包同步支持“在应用层面定义特性开关Feature Flags”。这意味着不再局限于插件内部注册开关应用本身也可以声明 Feature Flag并在用户设置页面统一管理。配套调整还包括backstage/plugin-user-settings重构了 Feature Flag 筛选功能并支持description属性便于在设置页为每个开关展示说明文字相关概念可参考仓库文档 docs/plugins/feature-flags.md。5.2 依赖同步升级app-defaults同时升级了对core-plugin-api1.3.0-next.1、core-app-api1.4.0-next.1、plugin-permission-react0.4.9-next.1等的依赖确保新特性在应用默认配置包括默认的首页、搜索栏等中可用。六、搜索自定义空结果组件backstage/plugin-search-react1.4.0-next.2为SearchResult组件新增noResultsComponent属性用于替换默认的“无结果”空状态。仓库实现位于 plugins/search-react/src/components/SearchResult/SearchResult.tsxnoResultsComponent?: JSX.Element作为可选 prop缺省时使用内置默认空状态传入时则渲染自定义内容。官方示例节选自变更日志SearchResult noResultsComponent{No results were found/} {({ results }) ( List {results.map(({ type, document }) { switch (type) { case custom-result-item: return ( CustomResultListItem key{document.location} result{document} / ); default: return ( DefaultResultListItem key{document.location} result{document} / ); } })} /List )} /SearchResult当搜索无命中时页面会展示自定义的 “No results were found” 提示而无需额外条件渲染。相关 Storybook 故事与单元测试分别位于 SearchResult.stories.tsx 与 SearchResult.test.tsx可供参考。七、ADR 插件从 Octokit 全面转向 UrlReaders7.1 破坏性变更与动机backstage/plugin-adr0.3.0-next.2与backstage/plugin-adr-backend0.2.5-next.2是本版本改动较大的插件ADR 插件现在可以处理 GitHub 之外的站点后端扩展出相应端点支撑这一能力。这是一次BREAKING变更ADR 插件改用UrlReaders读取文档原先基于 Octokit 的实现被完全移除你需要为所有希望获取 ADR 的站点配置 integrations参考仓库文档 docs/integrations/index.md 完成配置如需自定义读取行为可以像覆盖其他应用 API 一样覆盖AdrApi参考 docs/api/utility-apis.md 中关于应用级 API 覆盖的介绍。7.2 解析器规范说明补丁内容还澄清了默认 ADR 解析器支持MADR 规范 v2.x使用该格式的团队可以直接利用默认解析能力无需额外适配。八、techdocs-cli自定义预览应用techdocs/cli1.3.0-next.2为serve命令新增两个选项允许用自带应用而非内置应用进行预览。仓库命令行实现位于 packages/techdocs-cli/src/commands/index.ts--preview-app-bundle-path PATH_TO_BUNDLE指定预览应用 bundle 的路径--preview-app-port PORT指定预览服务的监听端口。命令行校验逻辑表明--preview-app-port只能与--preview-app-bundle-path搭配使用单独使用端口参数会报错。典型用法是先构建自己的 TechDocs 预览应用 bundle再通过serve命令挂载到自定义端口上调试。此外techdocs-cli 的日志输出增加了上下文信息便于排查错误来源。九、Catalog 与杂项补丁9.1 by-refs 端点支持 POST body 携带 fieldsbackstage/catalog-client1.3.0-next.2与backstage/plugin-catalog-backend1.7.0-next.2联动更新by-refs端点除 query 参数外现在也支持通过POST body传递fields字段减少复杂字段选择场景下的 URL 长度限制问题。9.2 Tech Radar 交互增强backstage/plugin-tech-radar0.6.0-next.2为图例条目增加高亮效果并在悬停时显示气泡提升雷达图的交互可读性。9.3 Catalog 前端EntityPeekAheadPopoverbackstage/plugin-catalog-react1.2.4-next.2新增可复用的EntityPeekAheadPopover弹层组件悬停时可展示关联实体的更多细节适合在列表页提供轻量的实体预览。9.4 其余值得留意的变更backstage/plugin-catalog-backend-module-github0.2.3-next.2修复catalogPath选项对 GitHub 事件的 glob 匹配问题backstage/plugin-kubernetes-backend0.9.1-next.2在 config schema 中补上缺失的googleServiceAccount认证提供者backstage/plugin-lighthouse0.3.14-next.2修复审计列表项与创建审计按钮跳转到错误 URL 的 bugbackstage/plugin-permission-react0.4.9-next.1、backstage/plugin-playlist0.1.5-next.2依赖swr升级至^2.0.0backstage/plugin-scaffolder-backend与plugin-scaffolder-backend-module-rails的 action 描述改以 Markdown 演示ActionsPage的富文本能力backstage/plugin-adr、plugin-search、plugin-techdocs、plugin-catalog等大量前端插件因核心包升级而同步发布补丁版本均为依赖更新无独立行为变化。十、升级建议与注意事项Scaffolder 相关代码将所有从backstage/plugin-scaffolder导入的公共类型、组件、Hooks 与scaffolderApiRef迁移到backstage/plugin-scaffolder-react并将rootRouteRef替换为scaffolderPlugin.routes.root/alpha类型统一改从backstage/plugin-scaffolder-react/alpha导入。新后端系统若你正在使用httpRouterFactory的自定义 index 逻辑需迁移到rootHttpRouterFactory的indexPath依赖loggerToWinstonLogger的代码应改从backstage/backend-common导入。ADR 插件升级后必须配置 integrations否则无法读取非 GitHub 站点的 ADR同时确认自己的 ADR 格式默认解析器支持 MADR v2.x。依赖锁定将better-sqlite3升级到^8.0.0以与backstage/create-app模板保持一致。验证手段升级后可运行curl http://localhost:7007/api/scaffolder/v2/actions确认新 action 示例是否正确暴露并参考example-app、example-backend的依赖清单见变更日志末尾核对各包版本是否对齐。结语v1.10.0-next.2 是一次典型的“架构整理型”迭代Scaffolder 通过拆分plugin-scaffolder-react厘清了公共 API 的归属新后端系统通过RootHttpRouterService与ServiceFactoryOrFunction进一步收敛服务抽象而搜索空状态、Tech Radar 交互、ADR 多站点支持等则持续充实了开发者门户的实用能力。理解这些迁移路径是平滑升级到 v1.10.0 并提前适配新 API 的关键。后续正式版发布后可对照 docs/releases 目录下的最终 changelog 确认 API 是否再有调整。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Backstage v1.10.0-next.2 变更深度解读：Scaffolder 包重构、后端根路由服务与前端新能力
Backstage v1.10.0-next.2 变更深度解读Scaffolder 包重构、后端根路由服务与前端新能力【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇文章围绕 Backstage 开源仓库 docs/releases/v1.10.0-next.2-changelog.md 中记录的 v1.10.0-next.2 预发布版本展开逐项剖析该版本中 Scaffolder 生态的包级重构、新后端系统中rootHttpRouterServiceRef的引入、应用级 Feature Flags、搜索空状态定制、ADR 插件向 UrlReaders 的迁移等关键变化。读完本文你将掌握该版本涉及的核心 API 迁移路径、破坏性变更的应对方案以及若干新特性的具体用法可直接用于升级排查与新功能开发。说明本文基于仓库中记录的next预发布版本变更日志整理所有 API 签名、命令与行为均以仓库当前内容为准。-next.x表示正式发布前的迭代版本接口在后续版本中可能继续调整。一、版本全景一次覆盖前后端与 CLI 的大范围迭代v1.10.0-next.2 是 Backstage v1.10.0 正式发布前的第二个迭代版本变更范围横跨前端核心包backstage/app-defaults、backstage/core-app-api、backstage/core-plugin-api同步引入“应用级 Feature Flags”能力后端系统new backend systembackstage/backend-app-api、backstage/backend-plugin-api、backstage/backend-common完成一批服务与类型的迁移重构其中包含BREAKING变更Scaffolder 生态新包backstage/plugin-scaffolder-react1.0.0-next.0诞生从backstage/plugin-scaffolder收编了大量公共类型、组件、Hooks 与 API 引用同时为 Actions 页面引入 Markdown 描述与示例 YAML搜索与雷达backstage/plugin-search-react支持自定义空结果组件backstage/plugin-tech-radar增加图例高亮与悬停气泡ADR 插件前端与后端同时重构全面改用 UrlReaders 读取站点内容CLI 工具techdocs/cli的serve命令新增自定义预览应用入口与端口参数。从仓库依赖关系看example-app0.2.79-next.2与example-backend0.2.79-next.2也在本版本中同步升级是观察上述变化落地效果的最佳参照。二、Scaffolder 生态重构plugin-scaffolder-react 包诞生2.1 新包定位与迁移背景本版本最重要的一件事是新增了backstage/plugin-scaffolder-react1.0.0-next.0。其Major Changes明确指出将backstage/plugin-scaffolder中常用的类型、组件、Hooks 以及scaffolderApiRef重新安置到该新包中以便所有需要与 Scaffolder 交互的前端代码能够轻松复用。从仓库源码可以印证这一迁移结果scaffolderApiRef定义于 plugins/scaffolder-react/src/api/ref.ts通过createApiRefScaffolderApi创建createScaffolderFieldExtension实现于 plugins/scaffolder-react/src/extensions/createScaffolderFieldExtension.tsx并由 plugins/scaffolder-react/src/extensions/index.ts 统一导出useCustomFieldExtensions、useCustomLayouts等 Hook 集中在 plugins/scaffolder-react/src/hooks/index.ts。2.2 弃用导出清单迁移指引backstage/plugin-scaffolder1.10.0-next.2对本版本开始弃用以下导出要求调用方改从backstage/plugin-scaffolder-react导入createScaffolderFieldExtension ScaffolderFieldExtensions useTemplateSecrets scaffolderApiRef ScaffolderApi ScaffolderUseTemplateSecrets TemplateParameterSchema CustomFieldExtensionSchema CustomFieldValidator FieldExtensionOptions FieldExtensionComponentProps FieldExtensionComponent ListActionsResponse LogEvent ScaffolderDryRunOptions ScaffolderDryRunResponse ScaffolderGetIntegrationsListOptions ScaffolderGetIntegrationsListResponse ScaffolderOutputlink ScaffolderScaffoldOptions ScaffolderScaffoldResponse ScaffolderStreamLogsOptions ScaffolderTask ScaffolderTaskOutput ScaffolderTaskStatus同时rootRouteRef导出也被弃用应改用scaffolderPlugin.routes.root。如果你正在使用这些符号升级时只需替换 import 语句的来源包符号名称保持不变因此迁移成本较低。2.3/alpha类型迁移原backstage/plugin-scaffolder中的/alpha类型被移除并迁移到backstage/plugin-scaffolder-react/alphacreateNextScaffolderFieldExtension FormProps NextCustomFieldValidator NextFieldExtensionComponentProps NextFieldExtensionOptions这意味着一批面向“下一代表单扩展”的实验性 API 有了更合适的归属包后续扩展 Scaffolder 自定义字段时应从新位置导入。2.4 打包内补丁Actions 页面内容增强backstage/plugin-scaffolder同步获得三项体验增强使用MarkdownContent组件渲染 action 描述使 Action 文档页能够展示更丰富的富文本内容在 Scaffolder Actions 文档页展示 action 的示例 YAML将children显式声明为可选 props以适配 React 18 的 Props 类型要求backstage/plugin-techdocs-react也做了同样的调整。三、Scaffolder 后端createTemplateAction 支持 examples 示例3.1 新能力动作示例backstage/plugin-scaffolder-backend1.10.0-next.2为createTemplateAction增加了examples选项。仓库源码 plugins/scaffolder-node/src/actions/createTemplateAction.ts 中examples?: TemplateExample[]其类型定义为{ description: string; example: string }[]见 plugins/scaffolder-node/src/actions/types.ts。定义一个带示例的 action 如下const actionExamples [ { description: Example 1, example: yaml.stringify({ steps: [ { action: test:action, id: test, input: { input1: value, }, }, ], }), }, ]; export function createTestAction() { return createTemplateAction({ id: test:action, examples: [ { description: Example 1, examples: actionExamples, }, ], // ...schema、handler 等其余配置 }); }3.2 通过 API 读取示例示例注册后可经 Scaffolder 的 actions API 查询默认后端地址为curl http://localhost:7007/api/scaffolder/v2/actions返回 JSON 中会包含examples与schema字段[ { id: test:action, examples: [ { description: Example 1, example: steps:\n - action: test:action\n id: test\n input:\n input1: value\n } ], schema: { input: { type: object, properties: { input1: { title: Input 1, type: string } } } } } ]仓库测试 plugins/scaffolder-backend/src/actions/createListScaffolderActionsAction.test.ts 验证了该行为action 列表会携带examples数组并且能正确处理“没有描述、schema 或示例”的 action。注意示例内容是由createTemplateAction注册的模板参数 schema 推导而来input1的标题Input 1与类型string正是 schema 中properties.input1的映射结果。四、后端系统演进根 HTTP 路由服务与 BREAKING 变更4.1 新增 RootHttpRouterServicebackstage/backend-plugin-api0.3.0-next.1新增rootHttpRouterServiceRef与RootHttpRouterService接口。仓库源码 packages/backend-plugin-api/src/services/definitions/RootHttpRouterService.ts 中的接口定义非常简洁export interface RootHttpRouterService { /** Registers a handler at the root of the backend router. * The path is required and may not be empty. */ use(path: string, handler: Handler): void; }该服务注册在coreServices中见 packages/backend-plugin-api/src/services/definitions/coreServices.ts用于在 Backend 路由的根层级注册处理器适合承载健康检查、根路径跳转等全局逻辑。同时backstage/backend-defaults0.1.5-next.1默认安装了这个新的根 HTTP 路由服务example-backend-next也随版本同步升级使用。4.2 httpRouterFactory 的破坏性变更backstage/backend-app-api0.3.0-next.1对插件级路由工厂做出BREAKING调整httpRouterFactory现在接受getPath选项不再接受indexPlugin若要设置自定义 index 路径应改用新的rootHttpRouterFactory并配置indexPath。从源码结构看rootHttpRouterFactory与httpRouterFactory形成了“根路由 / 插件路由”的分层根级 index 跳转与插件级路由挂载解耦便于在根层统一管理入口。4.3 loggerToWinstonLogger 迁移本版本将loggerToWinstonLogger从backstage/backend-plugin-api迁移至backstage/backend-common。仓库中大量模块plugin-app-backend、plugin-catalog-backend、各 catalog 后端模块、events 后端模块等均切换了导入来源。backstage/backend-common0.18.0-next.1同步把对 winstonLogger类型的依赖替换为backend-plugin-api中的LoggerService——由于LoggerService是Logger接口的子集这不构成破坏性变更。4.4 服务实例化与校验强化backend-app-api与backend-plugin-api还包含多项健壮性改进新增ServiceFactoryOrFunction类型用于同时接受ServiceFactory或() ServiceFactory两种形式createSpecializedBackend在传入重复服务实现时抛出错误尝试覆盖 plugin metadata 服务时将抛出错误backend-defaults确保自定义服务实现能够替换默认实现插件日志标签从pluginId改为pluginbackstage/backend-test-utils的startTestBackend现在默认包含所有核心服务的默认实现方便测试新后端系统插件。backstage/backend-common的createRootLogger也支持覆盖默认的service日志标签同时将better-sqlite3升级到^8.0.0。若你的packages/backend/package.json中锁定了旧版本可按backstage/create-app的提示升级- better-sqlite3: ^7.5.0, better-sqlite3: ^8.0.0,五、前端核心应用级 Feature Flags5.1 应用层面定义特性开关backstage/app-defaults、backstage/core-app-api、backstage/core-plugin-api三包同步支持“在应用层面定义特性开关Feature Flags”。这意味着不再局限于插件内部注册开关应用本身也可以声明 Feature Flag并在用户设置页面统一管理。配套调整还包括backstage/plugin-user-settings重构了 Feature Flag 筛选功能并支持description属性便于在设置页为每个开关展示说明文字相关概念可参考仓库文档 docs/plugins/feature-flags.md。5.2 依赖同步升级app-defaults同时升级了对core-plugin-api1.3.0-next.1、core-app-api1.4.0-next.1、plugin-permission-react0.4.9-next.1等的依赖确保新特性在应用默认配置包括默认的首页、搜索栏等中可用。六、搜索自定义空结果组件backstage/plugin-search-react1.4.0-next.2为SearchResult组件新增noResultsComponent属性用于替换默认的“无结果”空状态。仓库实现位于 plugins/search-react/src/components/SearchResult/SearchResult.tsxnoResultsComponent?: JSX.Element作为可选 prop缺省时使用内置默认空状态传入时则渲染自定义内容。官方示例节选自变更日志SearchResult noResultsComponent{No results were found/} {({ results }) ( List {results.map(({ type, document }) { switch (type) { case custom-result-item: return ( CustomResultListItem key{document.location} result{document} / ); default: return ( DefaultResultListItem key{document.location} result{document} / ); } })} /List )} /SearchResult当搜索无命中时页面会展示自定义的 “No results were found” 提示而无需额外条件渲染。相关 Storybook 故事与单元测试分别位于 SearchResult.stories.tsx 与 SearchResult.test.tsx可供参考。七、ADR 插件从 Octokit 全面转向 UrlReaders7.1 破坏性变更与动机backstage/plugin-adr0.3.0-next.2与backstage/plugin-adr-backend0.2.5-next.2是本版本改动较大的插件ADR 插件现在可以处理 GitHub 之外的站点后端扩展出相应端点支撑这一能力。这是一次BREAKING变更ADR 插件改用UrlReaders读取文档原先基于 Octokit 的实现被完全移除你需要为所有希望获取 ADR 的站点配置 integrations参考仓库文档 docs/integrations/index.md 完成配置如需自定义读取行为可以像覆盖其他应用 API 一样覆盖AdrApi参考 docs/api/utility-apis.md 中关于应用级 API 覆盖的介绍。7.2 解析器规范说明补丁内容还澄清了默认 ADR 解析器支持MADR 规范 v2.x使用该格式的团队可以直接利用默认解析能力无需额外适配。八、techdocs-cli自定义预览应用techdocs/cli1.3.0-next.2为serve命令新增两个选项允许用自带应用而非内置应用进行预览。仓库命令行实现位于 packages/techdocs-cli/src/commands/index.ts--preview-app-bundle-path PATH_TO_BUNDLE指定预览应用 bundle 的路径--preview-app-port PORT指定预览服务的监听端口。命令行校验逻辑表明--preview-app-port只能与--preview-app-bundle-path搭配使用单独使用端口参数会报错。典型用法是先构建自己的 TechDocs 预览应用 bundle再通过serve命令挂载到自定义端口上调试。此外techdocs-cli 的日志输出增加了上下文信息便于排查错误来源。九、Catalog 与杂项补丁9.1 by-refs 端点支持 POST body 携带 fieldsbackstage/catalog-client1.3.0-next.2与backstage/plugin-catalog-backend1.7.0-next.2联动更新by-refs端点除 query 参数外现在也支持通过POST body传递fields字段减少复杂字段选择场景下的 URL 长度限制问题。9.2 Tech Radar 交互增强backstage/plugin-tech-radar0.6.0-next.2为图例条目增加高亮效果并在悬停时显示气泡提升雷达图的交互可读性。9.3 Catalog 前端EntityPeekAheadPopoverbackstage/plugin-catalog-react1.2.4-next.2新增可复用的EntityPeekAheadPopover弹层组件悬停时可展示关联实体的更多细节适合在列表页提供轻量的实体预览。9.4 其余值得留意的变更backstage/plugin-catalog-backend-module-github0.2.3-next.2修复catalogPath选项对 GitHub 事件的 glob 匹配问题backstage/plugin-kubernetes-backend0.9.1-next.2在 config schema 中补上缺失的googleServiceAccount认证提供者backstage/plugin-lighthouse0.3.14-next.2修复审计列表项与创建审计按钮跳转到错误 URL 的 bugbackstage/plugin-permission-react0.4.9-next.1、backstage/plugin-playlist0.1.5-next.2依赖swr升级至^2.0.0backstage/plugin-scaffolder-backend与plugin-scaffolder-backend-module-rails的 action 描述改以 Markdown 演示ActionsPage的富文本能力backstage/plugin-adr、plugin-search、plugin-techdocs、plugin-catalog等大量前端插件因核心包升级而同步发布补丁版本均为依赖更新无独立行为变化。十、升级建议与注意事项Scaffolder 相关代码将所有从backstage/plugin-scaffolder导入的公共类型、组件、Hooks 与scaffolderApiRef迁移到backstage/plugin-scaffolder-react并将rootRouteRef替换为scaffolderPlugin.routes.root/alpha类型统一改从backstage/plugin-scaffolder-react/alpha导入。新后端系统若你正在使用httpRouterFactory的自定义 index 逻辑需迁移到rootHttpRouterFactory的indexPath依赖loggerToWinstonLogger的代码应改从backstage/backend-common导入。ADR 插件升级后必须配置 integrations否则无法读取非 GitHub 站点的 ADR同时确认自己的 ADR 格式默认解析器支持 MADR v2.x。依赖锁定将better-sqlite3升级到^8.0.0以与backstage/create-app模板保持一致。验证手段升级后可运行curl http://localhost:7007/api/scaffolder/v2/actions确认新 action 示例是否正确暴露并参考example-app、example-backend的依赖清单见变更日志末尾核对各包版本是否对齐。结语v1.10.0-next.2 是一次典型的“架构整理型”迭代Scaffolder 通过拆分plugin-scaffolder-react厘清了公共 API 的归属新后端系统通过RootHttpRouterService与ServiceFactoryOrFunction进一步收敛服务抽象而搜索空状态、Tech Radar 交互、ADR 多站点支持等则持续充实了开发者门户的实用能力。理解这些迁移路径是平滑升级到 v1.10.0 并提前适配新 API 的关键。后续正式版发布后可对照 docs/releases 目录下的最终 changelog 确认 API 是否再有调整。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
)
