2026/9/13 4:37:26
FEATURED · 精选文章 
Backstage v1.7.0-next.2 变更深度解析权限规则 ZodSchema 重构、目录位置分析器与 Scaffolder 动作升级指南【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文基于仓库内 docs/releases/v1.7.0-next.2-changelog.md 编写围绕该预发布版本中若干Breaking Changes与新增能力展开权限规则 API 引入 ZodSchema 参数校验、catalog 后端新增addLocationAnalyzers、catalog-import 的仓库 URL 探测逻辑迁移到后端、bazaar-backend 强制注入 identity以及 Scaffolder 的github:publish/publish:gitlab:merge-request动作增强。读完本文你将能对照版本差异完成已有 Backstage 应用后端插件、权限规则、catalog 导入流程的平滑升级并理解这些改动背后的源码设计意图。一、版本概览这是一份预发布next变更日志v1.7.0-next.2是 Backstage 主版本线中的一个next 预发布快照同一批变更会被逐步合入稳定版。该 changelog 按 npm 包粒度组织每个包分Minor Changes新增/破坏性变更与Patch Changes缺陷修复与依赖升级两类并列出其依赖包的同步版本。涉及的核心包包括包版本变更级别backstage/plugin-permission-common0.7.0-next.2MinorBREAKINGbackstage/plugin-permission-node0.7.0-next.2MinorBREAKINGbackstage/plugin-catalog-backend1.5.0-next.2Minorbackstage/plugin-catalog-import0.9.0-next.2MinorBREAKINGbackstage/plugin-catalog-node1.2.0-next.2Minorbackstage/plugin-playlist-backend0.2.0-next.2MinorBREAKINGbackstage/plugin-bazaar-backend0.2.0-next.2MinorBREAKINGbackstage/plugin-scaffolder-backend1.7.0-next.2Minorbackstage/plugin-techdocs-backend1.4.0-next.2Minorbackstage/backend-tasks0.3.6-next.2Patch其中权限规则 API 的改动是整个版本影响面最广的破坏性变更——它同时牵动了plugin-permission-common、plugin-permission-node、plugin-catalog-backend与plugin-playlist-backend四个包的 API 形状。二、重点变更一权限规则 API 强制 ZodSchema 参数校验BREAKING2.1 变更动机changelog 明确指出commit46b4a72cee在定义权限规则时现在必须提供一个描述该规则期望参数的 ZodSchema。引入它的目的有两个在 metadata 端点的响应中更好地描述规则参数供前端以结构化方式渲染条件编辑表单在规则真正执行之前对参数进行校验避免非法参数进入apply/toQuery逻辑。2.2 API 形状变化从分离参数到单一对象改动前的createPermissionRule中apply与toQuery的签名把参数作为独立的多个参数传入createPermissionRule({ apply: (resource, foo, bar) true, toQuery: (foo, bar) {}, });改动后参数被收敛为单个对象并新增必填的paramSchema字段createPermissionRule({ paramSchema: z.object({ foo: z.string().describe(Foo value to match), bar: z.string().describe(Bar value to match), }), apply: (resource, { foo, bar }) true, toQuery: ({ foo, bar }) {}, });2.3 源码印证参数类型被限制为原始类型这一“参数必须是对象 值只允许原始类型”的设计在当前仓库源码中有直接体现。plugins/permission-common/src/types/api.ts 中定义了export type PermissionRuleParam undefined | JsonPrimitive | JsonPrimitive[]; export type PermissionRuleParams | undefined | Recordstring, PermissionRuleParam;JsonPrimitive即 string / number / boolean / null 这类基础 JSON 值。因此 changelog 中“将参数的可能值限制为原始类型以及原始类型的数组”的约束正是由上述类型定义强制保证的——对象、嵌套结构等复杂类型无法通过编译期类型检查。在权限节点侧plugins/permission-node/src/integration/createPermissionRule.ts 中可以看到实现通过import { z } from zod/v3引用 Zod并调用assertPermissionRuleParamsSchema同目录permissionRuleParams.ts来校验参数 schema 的合法性。从源码结构可以推断规则注册时会持久化paramSchema并在条件决策执行前对入参做运行时校验从而保证 metadata 端点输出的参数描述与真实执行的参数一致。2.4 联动影响catalog 与 playlist 的权限条件 API由于PermissionRule类型发生破坏性变更所有基于它导出的权限规则都必须同步调整backstage/plugin-catalog-backendcommiteb25f7e12d导出的权限规则与createCatalogConditionalDecision的 API 随PermissionRule类型变更而改变涉及的类型全部从backstage/plugin-catalog-backend/alpha导出。实现位于 plugins/catalog-backend/src/permissions/conditionExports.ts。backstage/plugin-playlist-backendcommiteb25f7e12d以playlistConditions.isOwner为例调用方式从分离参数变为对象传参// 旧写法 playlistConditions.isOwner([user:default/me, group:default/owner]); // 新写法 playlistConditions.isOwner({ owners: [user:default/me, group:default/owner], });2.5 升级动作清单如果你在自己的 Backstage 应用或插件中定义了自定义权限规则请按以下步骤迁移为每条规则补充paramSchema使用z.object({ ... })描述字段建议用.describe()提供可读说明会出现在 metadata 响应中将apply/toQuery的参数由分散形参改为从单一对象中解构检查参数取值是否仅包含原始类型或原始类型数组复杂对象需拆分为多个参数若使用 catalog 的条件决策 API改为从backstage/plugin-catalog-backend/alpha导入相关类型。三、重点变更二Catalog 后端新增 Location Analyzer位置分析器3.1 新增addLocationAnalyzers方法commitb2e6cb6acf为CatalogBuilder增加了新方法addLocationAnalyzers。通过它可以向 catalog 注册若干location analyzer这些分析器会被/analyze-location端点用来判断用户提供的仓库 URL 中是否已经包含 catalog-info.yaml 文件从而决定在 catalog-import 页面中是引导用户注册已有实体还是帮用户生成新的 catalog-info.yaml。该方法在仓库中的实现位于 plugins/catalog-backend/src/service/CatalogBuilder.ts签名支持传入一个或多个ScmLocationAnalyzer或其数组并返回CatalogBuilder以支持链式调用addLocationAnalyzers( ...analyzers: ArrayScmLocationAnalyzer | ArrayScmLocationAnalyzer ): CatalogBuilder同时在 plugins/catalog-backend/src/service/CatalogPlugin.ts 中可以看到默认的 SCM 分析器通过builder.addLocationAnalyzers(...scmLocationAnalyzers)注入说明分析器机制已成为 catalog 后端初始化流程的一等公民。3.2 catalog-import 的仓库探测逻辑迁移到后端BREAKING与上一项配套的是backstage/plugin-catalog-import0.9.0-next.2的破坏性变更对 catalog-info.yaml 的代码搜索从前端迁移到了后端。这意味着搜索过程将使用已配置的 GitHub 集成凭据而非用户浏览器会话的凭据避免仓库中已有 catalog-info.yaml 却因前端无权限而探测失败的问题。要恢复“通过仓库 URL 导入repo URL ingestion”功能你需要在 catalog.ts 中注册 GitHub 分析器// catalog.ts import { GitHubLocationAnalyzer } from backstage/plugin-catalog-backend-module-github; ... builder.addLocationAnalyzers( new GitHubLocationAnalyzer({ discovery: env.discovery, config: env.config, }), ); ...配套地backstage/plugin-catalog-backend-module-github0.1.8-next.2新增了GitHubLocationAnalyzercommit7022aebf35并补充了GitHubEntityProvider缺失的 config schemacommit7edb5909e8。结合 changelog 中RepoLocationAnalyzer的表述可以推断addLocationAnalyzers注册的分析器会被RepoLocationAnalyzer汇总使用共同决定某 URL 是否已包含 catalog-info.yaml。3.3 配套的类型迁移与位置分析相关的 5 个类型从backstage/plugin-catalog-backend迁移到了backstage/plugin-catalog-commonplugin-catalog-common1.0.7-next.2commit823acaa88bAnalyzeLocationResponseAnalyzeLocationRequestAnalyzeLocationExistingEntityAnalyzeLocationGenerateEntityAnalyzeLocationEntityField升级时需要同步更新这些类型的 import 来源。另外backstage/plugin-catalog-node1.2.0-next.2将LocationSpec类型标记为Deprecated并从该包迁移到了backstage/plugin-catalog-commoncommit404366c853import 路径同样需要更新。四、重点变更三bazaar-backend 强制注入 identityBREAKINGbackstage/plugin-bazaar-backend0.2.0-next.2中createRouter现在要求必须传入identityApicommit8554533546。改动目的members 表新增了用户实体 ref 列该值通过identityApi从请求用户身份中提取。对packages/backend/src/plugins/bazaar.ts的适配示例如下import { PluginEnvironment } from ../types; import { createRouter } from backstage/plugin-bazaar-backend; import { Router } from express; export default async function createPlugin( env: PluginEnvironment, ): PromiseRouter { return await createRouter({ logger: env.logger, config: env.config, database: env.database, identity: env.identity, }); }同步地前端backstage/plugin-bazaar0.1.25-next.2也做了配套增强新增Overview Card展示最新或随机项目、ProjectPreview.tsx增加gridSize与useTablePagination属性commitf7c2855d76并把成员链接到对应的用户 catalog 实体commitc0352bbc69。后端 router 也新增了getLatestProjects端点可按传入的 limit 返回最新项目列表。五、重点变更四Scaffolder 动作增强与修复5.1github:publish支持 PR 同步要求backstage/plugin-scaffolder-backend1.7.0-next.2commit17ff77154c为github:publish动作新增选项控制合并前 PR 是否需要与默认分支保持最新up to date。在配置模板时你可以把该开关接入参数表单例如在 software template 的 properties 中暴露一个布尔字段并在 action 参数中传递给github:publish用于强制要求 PR 必须基于最新默认分支才能合并。5.2publish:gitlab:merge-request新增sourcePathcommita8e9848479为 GitLab 合并请求发布动作新增可选的sourcePath参数同时targetPath变为可选未指定时回退到当前 workspace 路径。这让同一个模板可以更灵活地控制 MR 的源目录与目标目录。5.3 其他修复commit4880d43e25修复 Bitbucket Server 默认分支设置问题backstage/plugin-scaffolder1.7.0-next.2RepoUrlPicker的allowed*值在渲染时被重置的 bug 修复commit98ae18b68f/next路由的 Scaffolder 与旧版TaskPage视图打通commit92e490d6b4NextRouter升级到react-jsonschema-formv5-betaalpha 导出commit1047baa926。六、其他值得关注的变更6.1 techdocs-backend 新增可选catalogClientbackstage/plugin-techdocs-backend1.4.0-next.2为createRoute参数新增可选的catalogClient参数commit7ced1b4076用于在 TechDocs 构建/读取流程中访问 catalog 数据属于向后兼容的增量能力。6.2 backend-tasks 新增配置读取函数backstage/backend-tasks0.3.6-next.2新增readTaskScheduleDefinitionFromConfigcommitd4fea86ea3用于从Config中读取TaskScheduleDefinition即任务调度计划。这意味着像 Bitbucket Cloud 发现类 provider 的调度配置可以迁移到app-config.yaml中声明而不是硬编码在代码里——本版本中backstage/plugin-catalog-backend-module-bitbucket-cloud0.1.4-next.2正是这样做的commitf66e696e7b可通过配置文件配置 schedule。6.3 Bitbucket 模块拆分与弃用backstage/plugin-catalog-backend-module-bitbucket0.2.4-next.2被弃用commit23f9199a0f官方建议迁移到backstage/plugin-catalog-backend-module-bitbucket-cloud该模块还新增了基于新 backend-plugin-api 的bitbucketCloudCatalogModulecommita9b91d39bbbackstage/plugin-catalog-backend-module-bitbucket-server。同时backstage/backend-common0.15.2-next.2修复了 Bitbucket Server 集成问题commitc44cf412de。6.4 安全性与代码规范类改动多个后端包统一执行了“用response.json替代response.send”commit2d3a5f09ab依据SECURITY.md涉及plugin-catalog-backend、backend-common、cli、plugin-airbrake-backend、plugin-badges-backend、plugin-graphql-backend、plugin-periskop-backend、plugin-permission-backend、plugin-rollbar-backend、plugin-search-backend、plugin-tech-insights-backend、plugin-user-settings-backend等plugin-user-settings-backend还改用Response.status而非.send(number)commitf3463b176b。这类改动属于响应序列化的一致性收口升级时无需业务改动。6.5 构建与脚手架backstage/create-app0.4.32-next.2在 Dockerfile 的yarn install与apt-get阶段启用cache mounts加速重复构建commit01dff06be4backstage/plugin-github-issues0.1.2-next.2为 GraphQL 查询增加了过滤与排序能力commitdf226e124c。七、升级检查清单综合以上变更从v1.7.0-next.1或更早版本升级到本快照时建议按此顺序逐项排查权限系统更新所有createPermissionRule调用补充paramSchemaZodSchema将apply/toQuery参数改为单一对象确认参数值为原始类型或其数组catalog/playlist 的权限条件调用改为对象传参。类型导入将AnalyzeLocation*5 个类型与LocationSpec的 import 源更新为backstage/plugin-catalog-common。catalog 后端如需保留“按仓库 URL 导入”能力在CatalogBuilder上调用addLocationAnalyzers注册GitHubLocationAnalyzer传入discovery与config。bazaar 插件向createRouter注入identity: env.identity。Scaffolder 模板按需使用github:publish的 PR 同步开关与publish:gitlab:merge-request的sourcePath检查targetPath省略时的默认行为。Bitbucket 模块将catalog-backend-module-bitbucket迁移到 cloud/server 拆分模块并将 provider 调度配置尽量下沉到app-config.yaml。依赖锁定参照 changelog 中各包的Updated dependencies列表如backstage/backend-common0.15.2-next.2、backstage/plugin-catalog-node1.2.0-next.2等同步升级避免子依赖版本不一致导致运行时行为漂移。需要说明的是本文所有 API 签名与类型定义均以当前仓库源码plugins/permission-common/src/types/api.ts、plugins/permission-node/src/integration/createPermissionRule.ts、plugins/catalog-backend/src/service/CatalogBuilder.ts与 docs/releases/v1.7.0-next.2-changelog.md 为准v1.7.0-next.2为预发布快照正式升级前请留意后续稳定版 changelog 是否对 API 有进一步调整。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Backstage v1.7.0-next.2 变更深度解析：权限规则 ZodSchema 重构、目录位置分析器与 Scaffolder 动作升级指南
Backstage v1.7.0-next.2 变更深度解析权限规则 ZodSchema 重构、目录位置分析器与 Scaffolder 动作升级指南【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文基于仓库内 docs/releases/v1.7.0-next.2-changelog.md 编写围绕该预发布版本中若干Breaking Changes与新增能力展开权限规则 API 引入 ZodSchema 参数校验、catalog 后端新增addLocationAnalyzers、catalog-import 的仓库 URL 探测逻辑迁移到后端、bazaar-backend 强制注入 identity以及 Scaffolder 的github:publish/publish:gitlab:merge-request动作增强。读完本文你将能对照版本差异完成已有 Backstage 应用后端插件、权限规则、catalog 导入流程的平滑升级并理解这些改动背后的源码设计意图。一、版本概览这是一份预发布next变更日志v1.7.0-next.2是 Backstage 主版本线中的一个next 预发布快照同一批变更会被逐步合入稳定版。该 changelog 按 npm 包粒度组织每个包分Minor Changes新增/破坏性变更与Patch Changes缺陷修复与依赖升级两类并列出其依赖包的同步版本。涉及的核心包包括包版本变更级别backstage/plugin-permission-common0.7.0-next.2MinorBREAKINGbackstage/plugin-permission-node0.7.0-next.2MinorBREAKINGbackstage/plugin-catalog-backend1.5.0-next.2Minorbackstage/plugin-catalog-import0.9.0-next.2MinorBREAKINGbackstage/plugin-catalog-node1.2.0-next.2Minorbackstage/plugin-playlist-backend0.2.0-next.2MinorBREAKINGbackstage/plugin-bazaar-backend0.2.0-next.2MinorBREAKINGbackstage/plugin-scaffolder-backend1.7.0-next.2Minorbackstage/plugin-techdocs-backend1.4.0-next.2Minorbackstage/backend-tasks0.3.6-next.2Patch其中权限规则 API 的改动是整个版本影响面最广的破坏性变更——它同时牵动了plugin-permission-common、plugin-permission-node、plugin-catalog-backend与plugin-playlist-backend四个包的 API 形状。二、重点变更一权限规则 API 强制 ZodSchema 参数校验BREAKING2.1 变更动机changelog 明确指出commit46b4a72cee在定义权限规则时现在必须提供一个描述该规则期望参数的 ZodSchema。引入它的目的有两个在 metadata 端点的响应中更好地描述规则参数供前端以结构化方式渲染条件编辑表单在规则真正执行之前对参数进行校验避免非法参数进入apply/toQuery逻辑。2.2 API 形状变化从分离参数到单一对象改动前的createPermissionRule中apply与toQuery的签名把参数作为独立的多个参数传入createPermissionRule({ apply: (resource, foo, bar) true, toQuery: (foo, bar) {}, });改动后参数被收敛为单个对象并新增必填的paramSchema字段createPermissionRule({ paramSchema: z.object({ foo: z.string().describe(Foo value to match), bar: z.string().describe(Bar value to match), }), apply: (resource, { foo, bar }) true, toQuery: ({ foo, bar }) {}, });2.3 源码印证参数类型被限制为原始类型这一“参数必须是对象 值只允许原始类型”的设计在当前仓库源码中有直接体现。plugins/permission-common/src/types/api.ts 中定义了export type PermissionRuleParam undefined | JsonPrimitive | JsonPrimitive[]; export type PermissionRuleParams | undefined | Recordstring, PermissionRuleParam;JsonPrimitive即 string / number / boolean / null 这类基础 JSON 值。因此 changelog 中“将参数的可能值限制为原始类型以及原始类型的数组”的约束正是由上述类型定义强制保证的——对象、嵌套结构等复杂类型无法通过编译期类型检查。在权限节点侧plugins/permission-node/src/integration/createPermissionRule.ts 中可以看到实现通过import { z } from zod/v3引用 Zod并调用assertPermissionRuleParamsSchema同目录permissionRuleParams.ts来校验参数 schema 的合法性。从源码结构可以推断规则注册时会持久化paramSchema并在条件决策执行前对入参做运行时校验从而保证 metadata 端点输出的参数描述与真实执行的参数一致。2.4 联动影响catalog 与 playlist 的权限条件 API由于PermissionRule类型发生破坏性变更所有基于它导出的权限规则都必须同步调整backstage/plugin-catalog-backendcommiteb25f7e12d导出的权限规则与createCatalogConditionalDecision的 API 随PermissionRule类型变更而改变涉及的类型全部从backstage/plugin-catalog-backend/alpha导出。实现位于 plugins/catalog-backend/src/permissions/conditionExports.ts。backstage/plugin-playlist-backendcommiteb25f7e12d以playlistConditions.isOwner为例调用方式从分离参数变为对象传参// 旧写法 playlistConditions.isOwner([user:default/me, group:default/owner]); // 新写法 playlistConditions.isOwner({ owners: [user:default/me, group:default/owner], });2.5 升级动作清单如果你在自己的 Backstage 应用或插件中定义了自定义权限规则请按以下步骤迁移为每条规则补充paramSchema使用z.object({ ... })描述字段建议用.describe()提供可读说明会出现在 metadata 响应中将apply/toQuery的参数由分散形参改为从单一对象中解构检查参数取值是否仅包含原始类型或原始类型数组复杂对象需拆分为多个参数若使用 catalog 的条件决策 API改为从backstage/plugin-catalog-backend/alpha导入相关类型。三、重点变更二Catalog 后端新增 Location Analyzer位置分析器3.1 新增addLocationAnalyzers方法commitb2e6cb6acf为CatalogBuilder增加了新方法addLocationAnalyzers。通过它可以向 catalog 注册若干location analyzer这些分析器会被/analyze-location端点用来判断用户提供的仓库 URL 中是否已经包含 catalog-info.yaml 文件从而决定在 catalog-import 页面中是引导用户注册已有实体还是帮用户生成新的 catalog-info.yaml。该方法在仓库中的实现位于 plugins/catalog-backend/src/service/CatalogBuilder.ts签名支持传入一个或多个ScmLocationAnalyzer或其数组并返回CatalogBuilder以支持链式调用addLocationAnalyzers( ...analyzers: ArrayScmLocationAnalyzer | ArrayScmLocationAnalyzer ): CatalogBuilder同时在 plugins/catalog-backend/src/service/CatalogPlugin.ts 中可以看到默认的 SCM 分析器通过builder.addLocationAnalyzers(...scmLocationAnalyzers)注入说明分析器机制已成为 catalog 后端初始化流程的一等公民。3.2 catalog-import 的仓库探测逻辑迁移到后端BREAKING与上一项配套的是backstage/plugin-catalog-import0.9.0-next.2的破坏性变更对 catalog-info.yaml 的代码搜索从前端迁移到了后端。这意味着搜索过程将使用已配置的 GitHub 集成凭据而非用户浏览器会话的凭据避免仓库中已有 catalog-info.yaml 却因前端无权限而探测失败的问题。要恢复“通过仓库 URL 导入repo URL ingestion”功能你需要在 catalog.ts 中注册 GitHub 分析器// catalog.ts import { GitHubLocationAnalyzer } from backstage/plugin-catalog-backend-module-github; ... builder.addLocationAnalyzers( new GitHubLocationAnalyzer({ discovery: env.discovery, config: env.config, }), ); ...配套地backstage/plugin-catalog-backend-module-github0.1.8-next.2新增了GitHubLocationAnalyzercommit7022aebf35并补充了GitHubEntityProvider缺失的 config schemacommit7edb5909e8。结合 changelog 中RepoLocationAnalyzer的表述可以推断addLocationAnalyzers注册的分析器会被RepoLocationAnalyzer汇总使用共同决定某 URL 是否已包含 catalog-info.yaml。3.3 配套的类型迁移与位置分析相关的 5 个类型从backstage/plugin-catalog-backend迁移到了backstage/plugin-catalog-commonplugin-catalog-common1.0.7-next.2commit823acaa88bAnalyzeLocationResponseAnalyzeLocationRequestAnalyzeLocationExistingEntityAnalyzeLocationGenerateEntityAnalyzeLocationEntityField升级时需要同步更新这些类型的 import 来源。另外backstage/plugin-catalog-node1.2.0-next.2将LocationSpec类型标记为Deprecated并从该包迁移到了backstage/plugin-catalog-commoncommit404366c853import 路径同样需要更新。四、重点变更三bazaar-backend 强制注入 identityBREAKINGbackstage/plugin-bazaar-backend0.2.0-next.2中createRouter现在要求必须传入identityApicommit8554533546。改动目的members 表新增了用户实体 ref 列该值通过identityApi从请求用户身份中提取。对packages/backend/src/plugins/bazaar.ts的适配示例如下import { PluginEnvironment } from ../types; import { createRouter } from backstage/plugin-bazaar-backend; import { Router } from express; export default async function createPlugin( env: PluginEnvironment, ): PromiseRouter { return await createRouter({ logger: env.logger, config: env.config, database: env.database, identity: env.identity, }); }同步地前端backstage/plugin-bazaar0.1.25-next.2也做了配套增强新增Overview Card展示最新或随机项目、ProjectPreview.tsx增加gridSize与useTablePagination属性commitf7c2855d76并把成员链接到对应的用户 catalog 实体commitc0352bbc69。后端 router 也新增了getLatestProjects端点可按传入的 limit 返回最新项目列表。五、重点变更四Scaffolder 动作增强与修复5.1github:publish支持 PR 同步要求backstage/plugin-scaffolder-backend1.7.0-next.2commit17ff77154c为github:publish动作新增选项控制合并前 PR 是否需要与默认分支保持最新up to date。在配置模板时你可以把该开关接入参数表单例如在 software template 的 properties 中暴露一个布尔字段并在 action 参数中传递给github:publish用于强制要求 PR 必须基于最新默认分支才能合并。5.2publish:gitlab:merge-request新增sourcePathcommita8e9848479为 GitLab 合并请求发布动作新增可选的sourcePath参数同时targetPath变为可选未指定时回退到当前 workspace 路径。这让同一个模板可以更灵活地控制 MR 的源目录与目标目录。5.3 其他修复commit4880d43e25修复 Bitbucket Server 默认分支设置问题backstage/plugin-scaffolder1.7.0-next.2RepoUrlPicker的allowed*值在渲染时被重置的 bug 修复commit98ae18b68f/next路由的 Scaffolder 与旧版TaskPage视图打通commit92e490d6b4NextRouter升级到react-jsonschema-formv5-betaalpha 导出commit1047baa926。六、其他值得关注的变更6.1 techdocs-backend 新增可选catalogClientbackstage/plugin-techdocs-backend1.4.0-next.2为createRoute参数新增可选的catalogClient参数commit7ced1b4076用于在 TechDocs 构建/读取流程中访问 catalog 数据属于向后兼容的增量能力。6.2 backend-tasks 新增配置读取函数backstage/backend-tasks0.3.6-next.2新增readTaskScheduleDefinitionFromConfigcommitd4fea86ea3用于从Config中读取TaskScheduleDefinition即任务调度计划。这意味着像 Bitbucket Cloud 发现类 provider 的调度配置可以迁移到app-config.yaml中声明而不是硬编码在代码里——本版本中backstage/plugin-catalog-backend-module-bitbucket-cloud0.1.4-next.2正是这样做的commitf66e696e7b可通过配置文件配置 schedule。6.3 Bitbucket 模块拆分与弃用backstage/plugin-catalog-backend-module-bitbucket0.2.4-next.2被弃用commit23f9199a0f官方建议迁移到backstage/plugin-catalog-backend-module-bitbucket-cloud该模块还新增了基于新 backend-plugin-api 的bitbucketCloudCatalogModulecommita9b91d39bbbackstage/plugin-catalog-backend-module-bitbucket-server。同时backstage/backend-common0.15.2-next.2修复了 Bitbucket Server 集成问题commitc44cf412de。6.4 安全性与代码规范类改动多个后端包统一执行了“用response.json替代response.send”commit2d3a5f09ab依据SECURITY.md涉及plugin-catalog-backend、backend-common、cli、plugin-airbrake-backend、plugin-badges-backend、plugin-graphql-backend、plugin-periskop-backend、plugin-permission-backend、plugin-rollbar-backend、plugin-search-backend、plugin-tech-insights-backend、plugin-user-settings-backend等plugin-user-settings-backend还改用Response.status而非.send(number)commitf3463b176b。这类改动属于响应序列化的一致性收口升级时无需业务改动。6.5 构建与脚手架backstage/create-app0.4.32-next.2在 Dockerfile 的yarn install与apt-get阶段启用cache mounts加速重复构建commit01dff06be4backstage/plugin-github-issues0.1.2-next.2为 GraphQL 查询增加了过滤与排序能力commitdf226e124c。七、升级检查清单综合以上变更从v1.7.0-next.1或更早版本升级到本快照时建议按此顺序逐项排查权限系统更新所有createPermissionRule调用补充paramSchemaZodSchema将apply/toQuery参数改为单一对象确认参数值为原始类型或其数组catalog/playlist 的权限条件调用改为对象传参。类型导入将AnalyzeLocation*5 个类型与LocationSpec的 import 源更新为backstage/plugin-catalog-common。catalog 后端如需保留“按仓库 URL 导入”能力在CatalogBuilder上调用addLocationAnalyzers注册GitHubLocationAnalyzer传入discovery与config。bazaar 插件向createRouter注入identity: env.identity。Scaffolder 模板按需使用github:publish的 PR 同步开关与publish:gitlab:merge-request的sourcePath检查targetPath省略时的默认行为。Bitbucket 模块将catalog-backend-module-bitbucket迁移到 cloud/server 拆分模块并将 provider 调度配置尽量下沉到app-config.yaml。依赖锁定参照 changelog 中各包的Updated dependencies列表如backstage/backend-common0.15.2-next.2、backstage/plugin-catalog-node1.2.0-next.2等同步升级避免子依赖版本不一致导致运行时行为漂移。需要说明的是本文所有 API 签名与类型定义均以当前仓库源码plugins/permission-common/src/types/api.ts、plugins/permission-node/src/integration/createPermissionRule.ts、plugins/catalog-backend/src/service/CatalogBuilder.ts与 docs/releases/v1.7.0-next.2-changelog.md 为准v1.7.0-next.2为预发布快照正式升级前请留意后续稳定版 changelog 是否对 API 有进一步调整。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
