企业官网建设流程全解析

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 system）：@backstage/backend-app-api、@backstage/backend-plugin-api、@backstage/backend-common完成一批服务与类型的迁移重构，其中包含BREAKING变更；
• Scaffolder 生态：新包@backstage/plugin-scaffolder-react@1.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-app@0.2.79-next.2与example-backend@0.2.79-next.2也在本版本中同步升级，是观察上述变化落地效果的最佳参照。

二、Scaffolder 生态重构：plugin-scaffolder-react 包诞生

2.1 新包定位与迁移背景

本版本最重要的一件事是新增了@backstage/plugin-scaffolder-react@1.0.0-next.0。其Major Changes明确指出：将@backstage/plugin-scaffolder中常用的类型、组件、Hooks 以及scaffolderApiRef重新安置到该新包中，以便所有需要与 Scaffolder 交互的前端代码能够轻松复用。

从仓库源码可以印证这一迁移结果：

• scaffolderApiRef定义于 plugins/scaffolder-react/src/api/ref.ts，通过createApiRef<ScaffolderApi>创建；
• 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-scaffolder@1.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/alpha：

createNextScaffolderFieldExtension FormProps NextCustomFieldValidator NextFieldExtensionComponentProps NextFieldExtensionOptions

这意味着一批面向“下一代表单扩展”的实验性 API 有了更合适的归属包，后续扩展 Scaffolder 自定义字段时应从新位置导入。

2.4 打包内补丁：Actions 页面内容增强

@backstage/plugin-scaffolder同步获得三项体验增强：

1. 使用MarkdownContent组件渲染 action 描述，使 Action 文档页能够展示更丰富的富文本内容；
2. 在 Scaffolder Actions 文档页展示 action 的示例 YAML；
3. 将children显式声明为可选 props，以适配 React 18 的 Props 类型要求（@backstage/plugin-techdocs-react也做了同样的调整）。

三、Scaffolder 后端：createTemplateAction 支持 examples 示例

3.1 新能力：动作示例

@backstage/plugin-scaffolder-backend@1.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 新增 RootHttpRouterService

@backstage/backend-plugin-api@0.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-defaults@0.1.5-next.1默认安装了这个新的根 HTTP 路由服务，example-backend-next也随版本同步升级使用。

4.2 httpRouterFactory 的破坏性变更

@backstage/backend-app-api@0.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-common@0.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改为plugin；
• @backstage/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 Flags

5.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-api@1.3.0-next.1、core-app-api@1.4.0-next.1、plugin-permission-react@0.4.9-next.1等的依赖，确保新特性在应用默认配置（包括默认的首页、搜索栏等）中可用。

六、搜索：自定义空结果组件

@backstage/plugin-search-react@1.4.0-next.2为SearchResult组件新增noResultsComponent属性，用于替换默认的“无结果”空状态。仓库实现位于 plugins/search-react/src/components/SearchResult/SearchResult.tsx：noResultsComponent?: 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 全面转向 UrlReaders

7.1 破坏性变更与动机

@backstage/plugin-adr@0.3.0-next.2与@backstage/plugin-adr-backend@0.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/cli@1.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 携带 fields

@backstage/catalog-client@1.3.0-next.2与@backstage/plugin-catalog-backend@1.7.0-next.2联动更新：by-refs端点除 query 参数外，现在也支持通过POST body传递fields字段，减少复杂字段选择场景下的 URL 长度限制问题。

9.2 Tech Radar 交互增强

@backstage/plugin-tech-radar@0.6.0-next.2为图例条目增加高亮效果，并在悬停时显示气泡，提升雷达图的交互可读性。

9.3 Catalog 前端：EntityPeekAheadPopover

@backstage/plugin-catalog-react@1.2.4-next.2新增可复用的EntityPeekAheadPopover弹层组件，悬停时可展示关联实体的更多细节，适合在列表页提供轻量的实体预览。

9.4 其余值得留意的变更

• @backstage/plugin-catalog-backend-module-github@0.2.3-next.2：修复catalogPath选项对 GitHub 事件的 glob 匹配问题；
• @backstage/plugin-kubernetes-backend@0.9.1-next.2：在 config schema 中补上缺失的googleServiceAccount认证提供者；
• @backstage/plugin-lighthouse@0.3.14-next.2：修复审计列表项与创建审计按钮跳转到错误 URL 的 bug；
• @backstage/plugin-permission-react@0.4.9-next.1、@backstage/plugin-playlist@0.1.5-next.2：依赖swr升级至^2.0.0；
• @backstage/plugin-scaffolder-backend与plugin-scaffolder-backend-module-rails的 action 描述改以 Markdown 演示ActionsPage的富文本能力；
• @backstage/plugin-adr、plugin-search、plugin-techdocs、plugin-catalog等大量前端插件因核心包升级而同步发布补丁版本，均为依赖更新，无独立行为变化。

十、升级建议与注意事项

1. Scaffolder 相关代码：将所有从@backstage/plugin-scaffolder导入的公共类型、组件、Hooks 与scaffolderApiRef迁移到@backstage/plugin-scaffolder-react，并将rootRouteRef替换为scaffolderPlugin.routes.root；/alpha类型统一改从@backstage/plugin-scaffolder-react/alpha导入。
2. 新后端系统：若你正在使用httpRouterFactory的自定义 index 逻辑，需迁移到rootHttpRouterFactory的indexPath；依赖loggerToWinstonLogger的代码应改从@backstage/backend-common导入。
3. ADR 插件：升级后必须配置 integrations，否则无法读取非 GitHub 站点的 ADR；同时确认自己的 ADR 格式（默认解析器支持 MADR v2.x）。
4. 依赖锁定：将better-sqlite3升级到^8.0.0以与@backstage/create-app模板保持一致。
5. 验证手段：升级后可运行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