Backstage v1.40.0-next.1 变更解读Scaffolder 后端 2.0 破坏性重构与 CLI 构建清理【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文基于 Backstage 官方仓库中的 v1.40.0-next.1 预发布变更日志 撰写聚焦该版本最核心的两大主题backstage/plugin-scaffolder-backend迈向 2.0.0 的一系列破坏性变更与废弃项清理以及backstage/cli对实验性构建标志的整理。读完本文你将掌握该版本中哪些 API 必须迁移、往哪里迁移、旧后端系统的createRouter如何被取代以及fetch:template动作参数、CLI 环境变量等具体改动可直接对照自身工程完成升级。说明-next.1属于发布候选分支的预发布版本本文所述变更最终可能随正式版微调文中代码路径与行为均以当前仓库源码为准。一、版本概览一次以清理为主线的预发布v1.40.0-next.1 的变更规模很大涉及数十个backstage/*包但真正产生 Breaking Change 的只有少数几个包绝大多数包仅是依赖版本跟随更新Patch Changes。从变更日志结构看本次预发布可以归纳为三条主线Scaffolder 后端 2.0.0Major移除长期被 re-export 的废弃符号、删除旧后端系统的createRouter、废弃一批任务存储相关类型Canon 0.5.0Minor按钮类组件默认尺寸由medium调整为smallCLI 与杂项Patch移除两个实验性环境变量标志、Rspack 改用新的ModuleFederationPlugin、TechDocs 键盘可访问性改进、通知支持按主题开关等。与仓库中其他正式版发布说明例如 v1.39.0 发布说明 中逐步移除旧后端系统支持的主题相比v1.40.0-next.1 延续并深化了 Backstage 持续清理旧后端系统、收敛公共 API 表面的一贯路线。二、核心变更backstage/plugin-scaffolder-backend2.0.0backstage/plugin-scaffolder-backend从 1.x 一跃到2.0.0-next.1是本版本号最大的包。在仓库源码中可以看到该包在package.json中标注的角色为backend-plugin当前工作区版本已推进到4.2.0-next.2package.json说明 2.0.0 只是主干版本演进中的一个里程碑后续仍会持续迭代。2.1 迁移一废弃 re-export 全部移除改从模块包导入变更日志33394db与73b94d7明确指出scaffolder-backend 长期以来把一批本不属于自己的符号 re-export 出来本版本一次性清理调用方必须改为从各自的模块包导入。完整迁移对照如下原导入位置已移除迁移后导入位置createPublishAzureActionbackstage/plugin-scaffolder-backend-module-azurecreatePublishBitbucketCloudActionbackstage/plugin-scaffolder-backend-module-bitbucket-cloudcreatePublishBitbucketServerAction、createPublishBitbucketServerPullRequestActionbackstage/plugin-scaffolder-backend-module-bitbucket-servercreatePublishBitbucketActionbackstage/plugin-scaffolder-backend-module-bitbucketcreatePublishGerritAction、createPublishGerritReviewActionbackstage/plugin-scaffolder-backend-module-gerritcreateGithubActionsDispatchAction、createGithubDeployKeyAction、createGithubEnvironmentAction、createGithubIssuesLabelAction、CreateGithubPullRequestActionOptions、createGithubRepoCreateAction、createGithubRepoPushAction、createGithubWebhookAction、createPublishGithubActionbackstage/plugin-scaffolder-backend-module-githubcreatePublishGitlabActionbackstage/plugin-scaffolder-backend-module-gitlabActionContext、createTemplateAction、executeShellCommand、ExecuteShellCommandOptions、fetchContents、TaskSecrets、TemplateActionbackstage/plugin-scaffolder-nodeSerializedTask、SerializedTaskEvent、TaskBroker、TaskBrokerDispatchOptions、TaskBrokerDispatchResult、TaskCompletionState、TaskContext、TaskEventType、TaskStatus、TemplateFilter、TemplateGlobalbackstage/plugin-scaffolder-nodeScaffolderEntitiesProcessorbackstage/plugin-catalog-backend-module-scaffolder-entity-model这一清理方向与仓库当前的模块化结构完全一致Git 平台相关的发布动作已分别下沉到 scaffolder-backend-module-github、scaffolder-backend-module-gitlab、scaffolder-backend-module-bitbucket-cloud 等独立包中任务与模板抽象则统一收敛到 scaffolder-node。从源码结构看scaffolder-backend 自身的 index.ts 现在只导出插件本体、内置动作与权限规则输入类型不再扮演中转站角色。2.2 迁移二/alpha不再导出插件旧createRouter删除a8fcf04是两个叠加的破坏性变更/alpha导出收缩import(backstage/plugin-scaffolder-backend/alpha)不再导出插件本身必须改回import(backstage/plugin-scaffolder-backend)。当前仓库中 alpha.ts 仅剩一行export * from ./service/alpha说明/alpha出口已不再承载插件入口只保留 alpha 阶段的内部服务符号。旧后端系统入口删除曾在旧后端系统中用于手工装配路由的createRouter函数及其RouterOptions类型被彻底移除。这一点在源码中有直接证据仓库中的 router.ts 仍然定义了RouterOptions接口和createRouter函数供新后端系统插件内部调用但它已被包内私有化——从 package.json 的导出结构看不再作为公共 API 暴露给旧后端系统的createPlugin装配流程。新后端系统通过 ScaffolderPlugin.ts 中基于createBackendPlugin的scaffolderPlugin完成注册与启动httpRouter.use(router)由核心服务接管。迁移要点仍在使用旧后端系统、通过createRouter手动挂载 scaffolder 的应用需迁移到新后端系统backend.add(import(backstage/plugin-scaffolder-backend))风格已迁移的应用只需把/alpha后缀从导入路径中移除即可。2.3 迁移三fetch:template的copyWithoutRender更名为copyWithoutTemplating73b94d7同时移除了fetch:template动作上早已废弃的copyWithoutRender选项必须改名为copyWithoutTemplating。在仓库源码 template.ts 中可以看到两个选项的语义差异copyWithoutRender已移除glob 匹配的文件/目录整体原样拷贝连路径都不做模板渲染copyWithoutTemplating现行匹配文件的内容不参与模板处理但路径仍会经过渲染。配套测试 template.test.ts 明确覆盖了copyWithoutTemplating的行为命中模式的文件内容不做模板化、路径仍渲染未命中模式的文件正常渲染。如果你的模板中写了copyWithoutRender请直接重命名为copyWithoutTemplating并确认你的使用场景是否需要路径也要渲染这一行为差异。2.4 新废弃任务存储与 Worker 相关类型进入待重设计名单本次除了移除还新增了一批DEPRECATIONSCreateWorkerOptions、DatabaseTaskStore、DatabaseTaskStoreOptions、TaskManager、TaskStoreCreateTaskOptions、TaskStoreCreateTaskResult、TaskStoreEmitOptions、TaskStoreListEventsOptions、TaskStoreRecoverTaskOptions、TaskStoreShutDownTaskOptions。变更日志明确指出目前没有明确的废弃替代路径这些类型将在后续版本中随新后端系统下 Worker 定义方式的重新设计而被移除。从源码看DatabaseTaskStore等目前仍是 router.ts 内部StorageTaskBroker的底层存储实现属于包内使用直接消费这些类型的自定义 TaskBroker / Worker 实现应关注后续 2.x 演进暂不引入新的强依赖。三、其他值得关注的变更3.1 CLI实验性构建标志清理与 Rspack 模块联邦升级backstage/cli0.32.2-next.0有四个功能性补丁移除BACKSTAGE_CLI_EXPERIMENTAL_BUILD_CACHE该实验性构建缓存标志被移除官方建议改用EXPERIMENTAL_RSPACK移除FORCE_REACT_DEVELOPMENT另一个实验性标志一并下线Rspack 模块联邦切换ModuleFederationPlugin改用module-federation/enhanced/rspack提供替代内置实现这与前端动态插件的模块联邦生态对齐Jest 缓存加载器仅用于前端包避免破坏真实 ESM 模块导入同时修复了--format json时 eslint 报告合并的问题。对普通用户的影响集中在环境变量层面如果你的启动/构建脚本里设置了上述两个实验性标志请删除若要实验性构建缓存能力迁移到EXPERIMENTAL_RSPACK体系。3.2 Canon 0.5.0按钮默认尺寸改为 smallbackstage/canon0.5.0-next.1调整了设计系统中两个基础组件的默认尺寸Button与IconButton的默认size均由medium改为small。若你的 Canon 页面依赖默认尺寸渲染升级后按钮会整体变小一号需要显式传入sizemedium恢复原状。3.3 功能补丁速览通知系统plugin-notifications、plugin-notifications-backend、plugin-notifications-common、scaffolder-backend-module-notifications同步新增用户可在某个 origin 内按 topic 开关通知的能力1fb5f06TechDocs 可访问性plugin-techdocs与plugin-techdocs-module-addons-contrib改进键盘可访问性9dde3ba搜索search-backend-module-techdocs导出默认文档 collator便于在索引期做文档转换b47ec38Catalogcatalog-client修复refreshEntity与addLocation的错误响应22fad0dcatalog-backend-module-gitlab为 GitLab API 调用增加限流重试57a0badScaffolder 各平台模块azure、bitbucket 系、gerrit、gitea、cookiecutter、confluence-to-markdown 等动作模块批量迁移到新的 zod schema 动作格式e89d7b6、7f710d2、ca9fdc0等scaffolder-node改用LoggerService替代Logger其他plugin-org支持 i18n4fe364f、plugin-user-settings补充翻译ab6d3dd。四、升级路径建议结合本版本与仓库现状升级到 v1.40.0-next.1或随后的正式版时建议按以下顺序排查替换废弃导入按 2.1 的对照表把所有从backstage/plugin-scaffolder-backend导入的动作创建函数、任务类型、模板类型改到对应模块包或backstage/plugin-scaffolder-node移除/alpha导入将backstage/plugin-scaffolder-backend/alpha的插件导入改为主入口若仍在用旧后端系统的createRouter请迁移到新后端系统可参考 新后端系统文档 与 后端插件开发指南清理模板参数全局搜索copyWithoutRender替换为copyWithoutTemplating清理环境变量删除BACKSTAGE_CLI_EXPERIMENTAL_BUILD_CACHE与FORCE_REACT_DEVELOPMENT的使用回归验证重点回归测试 Scaffolder 任务发布流程GitHub/GitLab/Bitbucket/Azure/Gerrit、fetch:template渲染、以及自定义动作的注册与执行仓库内对应模块的测试如 template.test.ts可作为行为基准。需要提醒的是-next.x是发布候选快照建议通过 Backstage 官方的 Upgrade Helper 工具核对目标版本后再执行依赖升级避免在主干上锁定预发布版本号。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Backstage v1.40.0-next.1 变更解读：Scaffolder 后端 2.0 破坏性重构与 CLI 构建清理
Backstage v1.40.0-next.1 变更解读Scaffolder 后端 2.0 破坏性重构与 CLI 构建清理【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文基于 Backstage 官方仓库中的 v1.40.0-next.1 预发布变更日志 撰写聚焦该版本最核心的两大主题backstage/plugin-scaffolder-backend迈向 2.0.0 的一系列破坏性变更与废弃项清理以及backstage/cli对实验性构建标志的整理。读完本文你将掌握该版本中哪些 API 必须迁移、往哪里迁移、旧后端系统的createRouter如何被取代以及fetch:template动作参数、CLI 环境变量等具体改动可直接对照自身工程完成升级。说明-next.1属于发布候选分支的预发布版本本文所述变更最终可能随正式版微调文中代码路径与行为均以当前仓库源码为准。一、版本概览一次以清理为主线的预发布v1.40.0-next.1 的变更规模很大涉及数十个backstage/*包但真正产生 Breaking Change 的只有少数几个包绝大多数包仅是依赖版本跟随更新Patch Changes。从变更日志结构看本次预发布可以归纳为三条主线Scaffolder 后端 2.0.0Major移除长期被 re-export 的废弃符号、删除旧后端系统的createRouter、废弃一批任务存储相关类型Canon 0.5.0Minor按钮类组件默认尺寸由medium调整为smallCLI 与杂项Patch移除两个实验性环境变量标志、Rspack 改用新的ModuleFederationPlugin、TechDocs 键盘可访问性改进、通知支持按主题开关等。与仓库中其他正式版发布说明例如 v1.39.0 发布说明 中逐步移除旧后端系统支持的主题相比v1.40.0-next.1 延续并深化了 Backstage 持续清理旧后端系统、收敛公共 API 表面的一贯路线。二、核心变更backstage/plugin-scaffolder-backend2.0.0backstage/plugin-scaffolder-backend从 1.x 一跃到2.0.0-next.1是本版本号最大的包。在仓库源码中可以看到该包在package.json中标注的角色为backend-plugin当前工作区版本已推进到4.2.0-next.2package.json说明 2.0.0 只是主干版本演进中的一个里程碑后续仍会持续迭代。2.1 迁移一废弃 re-export 全部移除改从模块包导入变更日志33394db与73b94d7明确指出scaffolder-backend 长期以来把一批本不属于自己的符号 re-export 出来本版本一次性清理调用方必须改为从各自的模块包导入。完整迁移对照如下原导入位置已移除迁移后导入位置createPublishAzureActionbackstage/plugin-scaffolder-backend-module-azurecreatePublishBitbucketCloudActionbackstage/plugin-scaffolder-backend-module-bitbucket-cloudcreatePublishBitbucketServerAction、createPublishBitbucketServerPullRequestActionbackstage/plugin-scaffolder-backend-module-bitbucket-servercreatePublishBitbucketActionbackstage/plugin-scaffolder-backend-module-bitbucketcreatePublishGerritAction、createPublishGerritReviewActionbackstage/plugin-scaffolder-backend-module-gerritcreateGithubActionsDispatchAction、createGithubDeployKeyAction、createGithubEnvironmentAction、createGithubIssuesLabelAction、CreateGithubPullRequestActionOptions、createGithubRepoCreateAction、createGithubRepoPushAction、createGithubWebhookAction、createPublishGithubActionbackstage/plugin-scaffolder-backend-module-githubcreatePublishGitlabActionbackstage/plugin-scaffolder-backend-module-gitlabActionContext、createTemplateAction、executeShellCommand、ExecuteShellCommandOptions、fetchContents、TaskSecrets、TemplateActionbackstage/plugin-scaffolder-nodeSerializedTask、SerializedTaskEvent、TaskBroker、TaskBrokerDispatchOptions、TaskBrokerDispatchResult、TaskCompletionState、TaskContext、TaskEventType、TaskStatus、TemplateFilter、TemplateGlobalbackstage/plugin-scaffolder-nodeScaffolderEntitiesProcessorbackstage/plugin-catalog-backend-module-scaffolder-entity-model这一清理方向与仓库当前的模块化结构完全一致Git 平台相关的发布动作已分别下沉到 scaffolder-backend-module-github、scaffolder-backend-module-gitlab、scaffolder-backend-module-bitbucket-cloud 等独立包中任务与模板抽象则统一收敛到 scaffolder-node。从源码结构看scaffolder-backend 自身的 index.ts 现在只导出插件本体、内置动作与权限规则输入类型不再扮演中转站角色。2.2 迁移二/alpha不再导出插件旧createRouter删除a8fcf04是两个叠加的破坏性变更/alpha导出收缩import(backstage/plugin-scaffolder-backend/alpha)不再导出插件本身必须改回import(backstage/plugin-scaffolder-backend)。当前仓库中 alpha.ts 仅剩一行export * from ./service/alpha说明/alpha出口已不再承载插件入口只保留 alpha 阶段的内部服务符号。旧后端系统入口删除曾在旧后端系统中用于手工装配路由的createRouter函数及其RouterOptions类型被彻底移除。这一点在源码中有直接证据仓库中的 router.ts 仍然定义了RouterOptions接口和createRouter函数供新后端系统插件内部调用但它已被包内私有化——从 package.json 的导出结构看不再作为公共 API 暴露给旧后端系统的createPlugin装配流程。新后端系统通过 ScaffolderPlugin.ts 中基于createBackendPlugin的scaffolderPlugin完成注册与启动httpRouter.use(router)由核心服务接管。迁移要点仍在使用旧后端系统、通过createRouter手动挂载 scaffolder 的应用需迁移到新后端系统backend.add(import(backstage/plugin-scaffolder-backend))风格已迁移的应用只需把/alpha后缀从导入路径中移除即可。2.3 迁移三fetch:template的copyWithoutRender更名为copyWithoutTemplating73b94d7同时移除了fetch:template动作上早已废弃的copyWithoutRender选项必须改名为copyWithoutTemplating。在仓库源码 template.ts 中可以看到两个选项的语义差异copyWithoutRender已移除glob 匹配的文件/目录整体原样拷贝连路径都不做模板渲染copyWithoutTemplating现行匹配文件的内容不参与模板处理但路径仍会经过渲染。配套测试 template.test.ts 明确覆盖了copyWithoutTemplating的行为命中模式的文件内容不做模板化、路径仍渲染未命中模式的文件正常渲染。如果你的模板中写了copyWithoutRender请直接重命名为copyWithoutTemplating并确认你的使用场景是否需要路径也要渲染这一行为差异。2.4 新废弃任务存储与 Worker 相关类型进入待重设计名单本次除了移除还新增了一批DEPRECATIONSCreateWorkerOptions、DatabaseTaskStore、DatabaseTaskStoreOptions、TaskManager、TaskStoreCreateTaskOptions、TaskStoreCreateTaskResult、TaskStoreEmitOptions、TaskStoreListEventsOptions、TaskStoreRecoverTaskOptions、TaskStoreShutDownTaskOptions。变更日志明确指出目前没有明确的废弃替代路径这些类型将在后续版本中随新后端系统下 Worker 定义方式的重新设计而被移除。从源码看DatabaseTaskStore等目前仍是 router.ts 内部StorageTaskBroker的底层存储实现属于包内使用直接消费这些类型的自定义 TaskBroker / Worker 实现应关注后续 2.x 演进暂不引入新的强依赖。三、其他值得关注的变更3.1 CLI实验性构建标志清理与 Rspack 模块联邦升级backstage/cli0.32.2-next.0有四个功能性补丁移除BACKSTAGE_CLI_EXPERIMENTAL_BUILD_CACHE该实验性构建缓存标志被移除官方建议改用EXPERIMENTAL_RSPACK移除FORCE_REACT_DEVELOPMENT另一个实验性标志一并下线Rspack 模块联邦切换ModuleFederationPlugin改用module-federation/enhanced/rspack提供替代内置实现这与前端动态插件的模块联邦生态对齐Jest 缓存加载器仅用于前端包避免破坏真实 ESM 模块导入同时修复了--format json时 eslint 报告合并的问题。对普通用户的影响集中在环境变量层面如果你的启动/构建脚本里设置了上述两个实验性标志请删除若要实验性构建缓存能力迁移到EXPERIMENTAL_RSPACK体系。3.2 Canon 0.5.0按钮默认尺寸改为 smallbackstage/canon0.5.0-next.1调整了设计系统中两个基础组件的默认尺寸Button与IconButton的默认size均由medium改为small。若你的 Canon 页面依赖默认尺寸渲染升级后按钮会整体变小一号需要显式传入sizemedium恢复原状。3.3 功能补丁速览通知系统plugin-notifications、plugin-notifications-backend、plugin-notifications-common、scaffolder-backend-module-notifications同步新增用户可在某个 origin 内按 topic 开关通知的能力1fb5f06TechDocs 可访问性plugin-techdocs与plugin-techdocs-module-addons-contrib改进键盘可访问性9dde3ba搜索search-backend-module-techdocs导出默认文档 collator便于在索引期做文档转换b47ec38Catalogcatalog-client修复refreshEntity与addLocation的错误响应22fad0dcatalog-backend-module-gitlab为 GitLab API 调用增加限流重试57a0badScaffolder 各平台模块azure、bitbucket 系、gerrit、gitea、cookiecutter、confluence-to-markdown 等动作模块批量迁移到新的 zod schema 动作格式e89d7b6、7f710d2、ca9fdc0等scaffolder-node改用LoggerService替代Logger其他plugin-org支持 i18n4fe364f、plugin-user-settings补充翻译ab6d3dd。四、升级路径建议结合本版本与仓库现状升级到 v1.40.0-next.1或随后的正式版时建议按以下顺序排查替换废弃导入按 2.1 的对照表把所有从backstage/plugin-scaffolder-backend导入的动作创建函数、任务类型、模板类型改到对应模块包或backstage/plugin-scaffolder-node移除/alpha导入将backstage/plugin-scaffolder-backend/alpha的插件导入改为主入口若仍在用旧后端系统的createRouter请迁移到新后端系统可参考 新后端系统文档 与 后端插件开发指南清理模板参数全局搜索copyWithoutRender替换为copyWithoutTemplating清理环境变量删除BACKSTAGE_CLI_EXPERIMENTAL_BUILD_CACHE与FORCE_REACT_DEVELOPMENT的使用回归验证重点回归测试 Scaffolder 任务发布流程GitHub/GitLab/Bitbucket/Azure/Gerrit、fetch:template渲染、以及自定义动作的注册与执行仓库内对应模块的测试如 template.test.ts可作为行为基准。需要提醒的是-next.x是发布候选快照建议通过 Backstage 官方的 Upgrade Helper 工具核对目标版本后再执行依赖升级避免在主干上锁定预发布版本号。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考