Backstage v1.12.0-next.1 更新解读：Scaffolder Zod Schema、TechDocs 代理与 501 错误处理全面落地

Backstage v1.12.0-next.1 更新解读：Scaffolder Zod Schema、TechDocs 代理与 501 错误处理全面落地

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

本篇技术解读以 Backstage 官方变更日志 docs/releases/v1.12.0-next.1-changelog.md 为骨架，梳理 v1.12.0 第二个预发布版本（-next.1）中所有 Minor Changes 与值得关注的 Patch Changes，并结合当前仓库源码逐一验证实现细节。读完本文，你将掌握：如何用 Zod 替代手写 JSON Schema 定义 Scaffolder Action 的输入输出、如何为 TechDocs 的 AWS S3 存储配置 HTTPS 代理、如何理解并迁移 GitLab Discovery 的branch/fallbackBranch配置，以及后端错误体系新增的NotImplementedError与 501 状态码映射机制。

版本概览：一次横跨 TechDocs、Catalog、Scaffolder 与后端平台的预发布

v1.12.0-next.1 是 v1.12.0 正式版发布前的第二个next里程碑，变更集中在四大方向：

• Scaffolder 生态：Action 的input/outputSchema 支持用 Zod 声明（Minor），任务流组件迁移至scaffolder-react（Minor）；
• TechDocs 工具链：@techdocs/cli generate --verbose输出 mkdocs 日志（Minor），TechDocs 节点层支持 AWS S3 的 HTTPS 代理（Minor）；
• Catalog 数据接入：增量摄取模块新增已知 Provider 列表端点（Minor），GitLab 发现配置branch弃用并迁移为fallbackBranch；
• 后端基础能力：@backstage/errors新增NotImplementedError，backend-app-api将其正确映射为 HTTP 501（Patch）。

此外，整个 monorepo 统一把msw依赖升级到^1.0.0，并把大量组件中的黑白配色改为"主题感知"（theme aware），替换已废弃的Button为LinkButton。

Scaffolder：用 Zod 声明 Action 的 input/output Schema

Minor Changes 核心：zod替代手写 JS/TS 类型与 JSON Schema

本次变更日志中最值得关注的开发体验提升来自 plugins/scaffolder-backend：

7d724d8ef56: Added the ability to be able to define an actionsinputandoutputschema usingzodinstead of hand writing types andjsonschema

在此之前，编写一个 Scaffolder Action 需要同时维护三份东西：TS 类型定义、手写 JSON Schema、以及 Action 的 handler 实现。现在你可以在createTemplateAction中直接以 Zod 回调函数的形式声明schema.input与schema.output，类型与校验规则只需写一次。

源码级实现：从 Zod 到 JSON Schema 的转换链路

在 plugins/scaffolder-node/src/actions/createTemplateAction.ts 中，createTemplateAction的类型签名同时支持两种写法：

• 键值对回调对象：{ [key in string]: (zImpl: typeof z) => z.ZodType }，即每个字段一个(z) => z.string()形式的函数；
• 整体函数定义：(zImpl: typeof z) => z.ZodType，即一个返回完整 Zod Schema 的函数。

函数实现内部会调用parseSchemas完成转换。在 plugins/scaffolder-node/src/actions/util.ts 中可以清楚看到这条链路：

import zodToJsonSchema from 'zod-to-json-schema'; import { z } from 'zod/v3'; export const parseSchemas = ( action: TemplateActionOptions<any, any, any>, ): { inputSchema?: Schema; outputSchema?: Schema } => { // 键值对回调对象写法：逐字段调用 z 生成对象 Schema if (isKeyValueZodCallback(action.schema.input)) { const input = z.object( Object.fromEntries( Object.entries(action.schema.input).map(([k, v]) => [k, v(z)]), ), ); return { inputSchema: zodToJsonSchema(input) as Schema, outputSchema: isKeyValueZodCallback(action.schema.output) ? (zodToJsonSchema( z.object( Object.fromEntries( Object.entries(action.schema.output).map(([k, v]) => [k, v(z)]), ), ), ) as Schema) : undefined, }; } // 整体函数写法：直接调用得到 ZodType 后转换 if (isZodFunctionDefinition(action.schema.input)) { return { inputSchema: zodToJsonSchema(action.schema.input(z)) as Schema, outputSchema: isZodFunctionDefinition(action.schema.output) ? (zodToJsonSchema(action.schema.output(z)) as Schema) : undefined, }; } return { inputSchema: undefined, outputSchema: undefined }; };

关键点在于：运行时系统内部仍然消费 JSON Schema（zod-to-json-schema负责把 Zod 对象转换为jsonschema格式的Schema），因此表单渲染、校验、文档生成等既有链路完全不受影响；而handler的ctx.input类型则通过z.infer<ReturnType<TInputSchema[key]>>从 Zod 定义自动推导，实现"声明即类型"。从源码结构看，这一能力是向后兼容的——不传schema或仍传手写 JSON Schema 的旧 Action 依旧可用。

配套变化：uiSchema独立成属性、任务流组件迁移

同一版本中 plugins/scaffolder-react 的两项调整与上述能力直接相关：

• 44941fc97eb：在 validationcontext中把uiSchema挪到独立属性，与组件开发及ui:options的访问方式对齐，避免校验逻辑与uiSchema混在同一命名空间；
• 8f4d13f21cf（与 plugins/scaffolder 同步）：useTaskStream、TaskBorder、TaskLogStream、TaskSteps从plugin-scaffolder移入plugin-scaffolder-react，使任务流 UI 能力可以在非 Scaffolder 插件（例如自定义前端插件）中复用。

此外值得记录的 Scaffolder 修复与改进还包括：

• be3cddaab5f：RepoUrlPicker获取凭据的逻辑现在也支持没有 owner 的目标（典型场景为 Bitbucket Server 的project/repo结构），本次同步更新了 plugins/scaffolder-node/src/actions/util.ts 中parseRepoUrl对不同 SCM 类型的必填参数校验分支；
• eb877bad736：当给scaffolder/next传入分组时，未分组的模板会自动归入 "Other Templates" 分组，避免模板"无处安放"。

TechDocs：CLI 输出 mkdocs 日志，S3 请求支持 HTTPS 代理

@techdocs/cli generate --verbose直接透传 mkdocs 输出

TechDocs 的本地生成调试一直是痛点：techdocs-cli在容器内执行mkdocs build，一旦失败很难定位是哪个 mkdocs 插件或语法出了问题。本次 packages/techdocs-cli 的 Minor Change 解决了这个问题：

8e465ce52e2: Running@techdocs/cli generatewith the--verboseflag will now print the mkdocs output.

升级后，执行生成命令时加上--verbose，即可把 mkdocs 的实时输出直接打印到终端：

yarn techdocs-cli generate --source-dir ./docs --output-dir ./site --verbose

在排查 mkdocs-material 版本兼容、插件加载失败等问题时，这一参数能让错误定位从"黑盒"变为"开箱即查"。

plugin-techdocs-node：AWS S3 请求的 HTTPS 代理支持

另一项 Minor Change（ea2bbef1b16，同时出现在@techdocs/cli与 plugins/techdocs-node 的变更中）为 TechDocs 的 AWS S3 发布器增加了HTTPS 代理支持。对于部署在需要出网代理的企业网络中的 Backstage 实例，此前 S3 上传请求无法走代理，导致 TechDocs 站点发布失败；本版本通过底层请求库（packages/integration-aws-node 的依赖升级同步引入）支持了标准 HTTPS 代理环境变量配置。

相关修复与前端联动

• bfe350ef4ce：修复删除陈旧文件时，如果目标目录同时包含非空子目录会删除失败的 bug，保证了 TechDocs 重新构建后旧静态资源的彻底清理；
• plugins/techdocs 前端侧：54a1e133b56修复了特定 mkdocs-material 版本下 "Next/Previous" 翻页链接失效的问题；238cf657c09让"复制到剪贴板"在非安全上下文（非 HTTPS 页面）中也能工作；
• plugins/techdocs-backend 的40298b02778增强了构建失败时对"文档找不到"原因的解释性错误信息。

Catalog：增量摄取 Provider 列表端点与 GitLab 配置迁移

增量摄取：查询已知 Provider 的新端点

plugins/catalog-backend-module-incremental-ingestion 本次升级到0.3.0-next.1，带来一项 Minor Change：

a811bd246c4: Added endpoint to get a list of known incremental entity providers

配合该项新端点，运维人员可以通过 HTTP 接口直接查看当前已注册的增量实体 Provider 清单，用于排查"某个 Provider 是否被正确注册/加载"的常见问题，而不必翻查启动日志。

GitLab Discovery：branch弃用，改用fallbackBranch

这是一个必须主动跟进的破坏性（虽不立即生效）变更，来自 plugins/catalog-backend-module-gitlab：

af1095f1e11: The configuration keybranchof theGitlabDiscoveryEntityProviderhas been deprecated in favor of the configuration keyfallbackBranch. It will be reused in future release to enforce a concrete branch to be used in catalog file discovery. To migrate, renamebranchtofallbackBranch.

即：GitlabDiscoveryEntityProvider的配置项branch更名为fallbackBranch；未来版本将复用branch这个键来强制指定catalog 文件发现使用的具体分支。迁移方式非常直接——把 app-config 中的branch键改名为fallbackBranch即可：

catalog: providers: gitlab: yourProviderId: host: gitlab.example.com group: backstage # 迁移前：branch: master # 迁移后： fallbackBranch: master

从源码 plugins/catalog-backend-module-gitlab/src/providers/config.ts 可以看到配置解析的完整逻辑：branch仍通过config.getOptionalString('branch')读取（兼容期保留），而fallbackBranch默认值为'master'：

const branch = config.getOptionalString('branch'); const fallbackBranch = config.getOptionalString('fallbackBranch') ?? 'master';

同一文件中还可以看到GitlabDiscoveryEntityProvider的其它可用配置项：group、host、entityFilename（默认catalog-info.yaml）、projectPattern/userPattern/groupPattern、useSearch、orgEnabled、allowInherited、relations、skipForkedRepos、includeArchivedRepos、excludeRepos、schedule、restrictUsersToGroup、includeUsersWithoutSeat、topics等。

Catalog 核心与前端：批处理查询修复、columns属性扩展

• plugins/catalog-backend 的f093ce83d58修复了按 ref 批量获取端点在叠加过滤条件（例如开启鉴权后）时失效的 bug；
• plugins/catalog 与 plugins/api-docs 的c9a9f3c834f/9820eb5d24f：为基于EntityTable的组件新增columnsprop，便于按需自定义列；
• 7e8930ae1c6修复CatalogSearchResultListItem中图标对齐问题。

后端平台：NotImplementedError与 501 状态码

@backstage/errors新增标准错误类型

packages/errors 的3bf83a2aabf新增了NotImplementedError，语义定义为"服务器无法识别请求方法且无法为任何资源支持该方法"。该错误继承自CustomErrorBase，与InputError、NotFoundError、ConflictError等并列，实现在 packages/errors/src/errors/common.ts：

/** * The server does not support the functionality required to fulfill the request. * * @public */ export class NotImplementedError extends CustomErrorBase { name = 'NotImplementedError' as const; }

从源码注释可以看出，这类错误专门设计为被后端错误处理中间件识别并翻译成规范的 HTTP 响应。

backend-app-api：错误到 HTTP 501 的映射

packages/backend-app-api 的915e46622cf正是补上了这一环——它让错误处理逻辑识别NotImplementedError并正确返回 501 状态码。这意味着插件或自定义后端模块在实现"尚未支持"的接口时，可以直接抛出NotImplementedError，由框架层统一转换为符合 HTTP 语义的501 Not Implemented响应，而不是笼统的 500。

其它后端基础设施变更

• packages/backend-defaults 的5d0693edc09为@backstage/backend-common与@backstage/backend-app-api之间的循环依赖 bug 增加了 workaround；
• plugins/permission-node 的27a103ca07b放宽了 createPermissionIntegrationRouter 的 API——getResources、resourceType、rules均变为可选，让仅需权限列表注册的简单场景不必再传空实现；
• plugins/linguist-backend 的b271d5ca052允许通过kind配置指定要处理的实体类型：

return createRouter({ schedule: schedule, kind: ['Component'] }, { ...env });

• 大量后端包的文档链接统一更新（482dae5de1c）。

前端组件与 UI 一致化：主题感知、LinkButton与无障碍

本次版本中一个横切几乎所有前端插件的主题是UI 一致化，具体表现为三条贯穿性变更：

1. 黑白配色主题感知（cb8ec97cdeb）：plugin-catalog、core-components、plugin-azure-sites、plugin-code-climate、plugin-code-coverage、plugin-explore、plugin-firehydrant、plugin-gcalendar、plugin-git-release-manager、plugin-ilert、plugin-microsoft-calendar、plugin-newrelic-dashboard、plugin-org、plugin-shortcuts、plugin-tech-radar、plugin-techdocs等插件中硬编码的黑色/白色字色与背景色改为从当前主题（theme）取值，解决了暗色主题下文字不可见的问题；
2. LinkButton替换废弃Button（c10384a9235）：core-components、plugin-scaffolder、plugin-circleci、plugin-entity-validation、plugin-explore、plugin-kubernetes、plugin-playlist、plugin-techdocs统一改用LinkButton；
3. 无障碍改进：core-components的e1aae2f5a0c更新了HeaderTabs组件的aria-label。

另外 plugins/tech-radar 的e14dcfa4994将配色更新为与 Zalando 的 Tech Radar 一致，并为标题和图例增加了与环（ring）颜色匹配的上色。

工程化与依赖升级：msw 1.0 时代

本版本中一个全仓库范围的 Patch 级变更值得注意：msw（Mock Service Worker）依赖从0.x统一升级到^1.0.0（52b0022dab7），波及plugin-scaffolder、plugin-scaffolder-backend、backend-common、catalog-client、core-app-api、core-components、core-plugin-api、integration、test-utils以及绝大多数插件包。对应用开发者而言，这意味着测试环境的 mock 基础设施切换到 msw 1.x 语义，如果自建测试中直接依赖了 msw 的内部 API，升级时需对照 msw 1.0 的破坏性变更说明进行调整；对普通使用者则基本无感知。

packages/cli 侧同步做了配套更新：

• 9bf50a36674：模板中的msw版本直接提升到1.0.0；
• 1ad8d885d30：修复本地开发时后端包额外入口未被正确标记为 internal 的问题；
• 867f4752ca1：yarn start --check启用的 ESLint 插件配置现在只捡取有效的源文件；
• a11b9a23f5a：保留 package.json 中自定义的 exports 入口；
• 4b4998466b4：del依赖升级到^7.0.0。

升级建议与注意事项

结合本版本变更，建议在升级到 v1.12.0（及其中间版本）时重点核对以下几点：

1. GitLab Discovery 配置迁移：立即把catalog.providers.gitlab.<id>.branch重命名为fallbackBranch（默认值为master），避免未来版本branch语义变更带来的行为差异；
2. NotImplementedError使用：自定义后端模块中遇到"方法/能力尚未实现"的场景，优先抛出 packages/errors 的NotImplementedError，框架会自动返回 501，便于调用方准确区分"不存在"（404）与"未实现"（501）；
3. Scaffolder Action 重写：新编写的 Action 可直接使用 Zod 声明input/outputSchema（参考 plugins/scaffolder-node/src/actions/createTemplateAction.ts），运行时由parseSchemas转换为 JSON Schema，类型由z.infer自动推导；
4. TechDocs S3 出网环境：如部署在需要代理的网络中，升级@techdocs/cli与plugin-techdocs-node后可正常走 HTTPS 代理发布 S3 存储；调试生成失败时善用--verbose；
5. 依赖升级：msw 1.0 升级主要影响测试代码，scaffolder-react中的任务流组件导出是新增位置，若曾直接从plugin-scaffolder内部路径导入这些符号，请改为从plugin-scaffolder-react导入。

完整变更明细可对照 docs/releases/v1.12.0-next.1-changelog.md，并参考本仓库中对应包的CHANGELOG.md（例如 packages/backend-app-api/CHANGELOG.md、packages/errors/CHANGELOG.md）追踪正式发布前的后续迭代。

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