Backstage v1.22.0 版本深度解析动态后端插件服务落地与新前端系统app/root重构【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文基于 Backstage 官方仓库 v1.22.0 版本变更日志3239 行覆盖 100 软件包系统梳理该版本的核心升级脉络。v1.22.0 是 Backstage 在新前端系统New Frontend System与动态插件Dynamic Plugins两条主线上持续收敛的重要版本一方面首个backstage/backend-dynamic-feature-service包正式发布开启后端插件运行时加载能力另一方面app/router扩展点被重命名为app/root并开放了向 React 树根部注入元素的能力。读完本文你将掌握 v1.22.0 的破坏性变更、新扩展点用法、Scaffolder 新增的内置 action以及升级时需要注意的依赖与兼容性细节。一、版本总览四个 Minor 变更与两个新包v1.22.0 的变更主要集中在四个带 Minor Changes 的包以及两个全新发布的首版0.x包包版本变更类型核心内容backstage/backend-dynamic-feature-service0.1.0新包动态前端/后端插件及模块的发现与后端加载backstage/frontend-app-api0.5.0MinorBREAKINGapp/router扩展点重命名为app/rootbackstage/frontend-plugin-api0.5.0MinorBREAKING同步app/router→app/root重命名新增根级扩展能力backstage/plugin-app-visualizer0.1.0新包App 可视化插件首版发布backstage/plugin-scaffolder-backend1.20.0Minor新增 Bitbucket Cloud Pipeline 与gitlab:repo:pushactionbackstage/plugin-user-settings0.8.0Minor语言选择器改用原生语言名称显示除上述包外其余 100 个包均为 Patch 变更主要是依赖升级、依赖清理changeset4016f21移除未使用依赖与 bug 修复。注意example-app、example-backend等示例包也随之一并升级见 v1.22.0-changelog.md可作为升级后的集成参考。二、backstage/backend-dynamic-feature-service0.1.0后端动态插件能力的正式起点2.1 这个包解决什么问题changeseteb81f42给出了清晰的定义该包用于动态前端与后端插件及模块的发现discovery以及在后端应用中加载后端插件。在此之前Backstage 后端插件必须在应用的package.json中静态声明而 v1.22.0 引入了运行时加载的路径——插件可以作为独立产物分发部署时放入一个独立目录无需重新构建整个后端应用。仓库中该包的 README 明确列出了四点设计目标插件分发插件可作为独立产物分发运行时灵活性增删插件无需重建整个应用隔离性插件专属依赖与核心应用依赖分离模块化部署不同环境可加载不同的插件集合。2.2 核心架构与加载链路从 packages/backend-dynamic-feature-service/src 的目录结构可以还原出四条核心链路Plugin Scannersrc/scanner/plugin-scanner.ts扫描配置目录dynamicPlugins.rootDirectory识别合法的插件包Module Loadersrc/loader/CommonJSModuleLoader.ts通过 CommonJS 加载后端插件模块Feature Loadersrc/features/features.ts把加载到的插件注册为 Backstage featureFrontend Asset Serversrc/server/frontendRemotesServer.ts通过 HTTP 对外提供动态前端插件的 JS/CSS/manifest 资产。扫描器会对每个候选包校验main与backstage.role字段role 必须为backend-plugin或backend-plugin-module测试夹具 src/features/fixtures/dynamic-plugins-root 中的test-backend-dynamic与test-dynamic目录展示了后端插件与前端含mf-manifest.json、remoteEntry.js的 Module Federation 产物两类动态插件的典型形态。2.3 启用方式与配置在应用入口添加一行即可启用import { createBackend } from backstage/backend-defaults; import { dynamicPluginsFeatureLoader } from backstage/backend-dynamic-feature-service; const backend createBackend(); // 启用动态插件支持 backend.add(dynamicPluginsFeatureLoader); // ... 其他插件 backend.start();配置文件app-config.yaml中指定动态插件目录dynamicPlugins: rootDirectory: dynamic-plugins-root2.4 动态插件的打包方式该服务只负责加载打包分发由独立流程完成。README 提供了三种递进方案方案一直接yarn pack仅当插件只用主应用已提供的依赖cd my-backstage-plugin yarn pack # 得到 package.tgz mkdir -p /path/to/dynamic-plugins-root/my-backstage-plugin tar -xzf package.tgz -C /path/to/dynamic-plugins-root/my-backstage-plugin --strip-components1该方案的适用面有限因为多数插件都有主应用中不存在的私有依赖。方案二手动打包并安装私有依赖cd my-backstage-plugin yarn pack mkdir -p /path/to/dynamic-plugins-root/my-backstage-plugin tar -xzf package.tgz -C /path/to/dynamic-plugins-root/my-backstage-plugin --strip-components1 cp yarn.lock /path/to/dynamic-plugins-root/my-backstage-plugin cd /path/to/dynamic-plugins-root/my-backstage-plugin yarn install # 安装插件全部依赖典型场景插件需要主应用中不存在的axios1.4.0。方案三backstage-cli package bundle推荐自包含产物cd my-backstage-plugin yarn backstage-cli package bundle --output-destination /path/to/dynamic-plugins-root批量打包同一 monorepo 下多个插件时可用--pre-packed-dir复用构建产物backstage-cli build-workspace dist-workspace --alwaysPack ...plugin-packages cd plugins/my-backstage-plugin backstage-cli package bundle --pre-packed-dir ../../dist-workspace该命令会自动完成构建插件 CJS 产物 → 打包workspace:^/backstage:^本地依赖 → 播种并裁剪 lockfile 后安装私有node_modules→ 收集插件配置 schema 写入dist/.config-schema.json供加载期校验。产出物解压即用无需后续安装步骤。三、新前端系统里程碑app/router→app/root重命名与根级扩展3.1 破坏性变更升级前必须知晓changesetd4149bf同时作用于backstage/frontend-app-api0.5.0与backstage/frontend-plugin-api0.5.0将app/router扩展点重命名为app/root。任何在扩展配置、createExtension的attachTo或扩展覆盖中引用app/router的代码都必须同步改名。仓库内测试已全面跟进在 createSpecializedApp.test.tsx 中可以看到大量attachTo: { id: app/root, input: elements }的用法treeLifecycle.tsx 中tree.nodes.get(app/root)也以app/root作为根节点标识。如果你的应用仍在使用app/router升级 v1.22.0 后将无法解析到该扩展点请一并迁移。3.2app/root的新增 inputselements、wrappers、routerchangesetc97fa1c为app/root新增了三个输入点让你可以在布局之上的 React 树根部挂载内容elements向根级插入元素如 OAuth 对话框、Alert 提示等见 changeset5fe6600——根元素现已内置 oauth dialog 与 alert 展示wrappers包裹整个应用的包装组件router替换默认路由。对应三个便捷的扩展创建器扩展创建器挂载位置说明createAppRootElementExtensionapp/root的elementsinput在布局之上渲染元素createAppRootWrapperExtensionapp/root的wrappersinput包裹应用树createRouterExtensionapp/root的routerinput自定义路由组件三者均为可选。若不提供 router将使用默认路由常规运行下为BrowserRouter测试/CI 环境为MemoryRouter——这一约定与frontend-test-utils的测试行为保持一致见 changesetf7566f9对测试工具的同步更新。因此测试代码无需显式注入 MemoryRouter默认行为即满足隔离要求。3.3 更宽容的错误处理与其他 API 打磨changeset074dfe3向不存在的 input 挂载扩展从 error 降级为warning。这意味着新前端系统对插件间的解耦更宽容某一扩展点缺失时不再让整个应用启动失败但日志中仍会保留提示以便排查。changesetb2d370efrontend-plugin-api暴露createComponentRef并确保生成的 ref 与 feature bit 具备toString方法便于调试输出。changeset7d63b32createPlugin的 routes 映射现在接受子路由 refsub route refs为插件内层级路由的组织提供支持。changeset4c1f50ccore-compat-apiconvertLegacyApp会用compatWrapper包裹发现到的路由保证旧前端系统插件在新系统中兼容运行。四、新插件首秀backstage/plugin-app-visualizer0.1.0changesete57cc9f带来 app visualizer 插件的首个版本。该插件用于可视化前端应用中的插件与扩展构成帮助开发者直观检查新前端系统的扩展点接线情况。其依赖面很轻仅依赖frontend-plugin-api0.5.0、core-components0.13.10、core-plugin-api1.8.2源码位于 plugins/app-visualizer是理解新前端系统结构的上手示例。它被示例应用example-app-next采纳见 v1.22.0-changelog.md。五、Scaffolder新增两个 GitLab/Git 相关 action 与权限修复5.1gitlab:repo:push向任意分支推送文件而不创建 MRchangeset7c522c5在backstage/plugin-scaffolder-backend-module-gitlab0.2.12中新增gitlab:repo:push可直接向任意分支提交文件无需走 Merge Request 流程。其实现位于 gitlabRepoPush.tsschema 定义含输入输出参数如下createTemplateAction({ id: gitlab:repo:push, schema: { input: { repoUrl: // 形如 gitlab.com?repoproject_nameownergroup_name branchName: // 提交目标分支名 commitMessage: // 提交信息 sourcePath: // 可选从工作目录哪个子目录取变更 targetPath: // 可选仓库内哪个子目录接收变更 token: // 可选GitLab 授权 token commitAction: // 可选create | update | delete | auto默认 create allowEmpty: // 可选是否允许空提交 }, output: { projectid: // GitLab Project id/name(slug) projectPath: // GitLab Project path commitHash: // 提交哈希无文件变更且 allowEmpty 非 true 时省略 }, }, })配套的 gitlabRepoPush.examples.ts 与 gitlabRepoPush.examples.test.ts 提供了可直接复制的模板参数示例与测试用例。5.2 配套的gitlab:issues:create与 Bitbucket Cloud Pipeline同版本中gitlab:issues:createchangeset604c9dd实现在 gitlabIssueCreate.ts用于创建 GitLab Issue而 changeseta694f71在backstage/plugin-scaffolder-backend-module-bitbucket中加入运行 Bitbucket Cloud Rest API Pipeline的 action。至此 Scaffolder 内置 action 的代码托管覆盖面进一步扩大Bitbucket/GitLab/GitHub/Gerrit 等模块在 plugins 下均有对应实现。5.3 权限条件修复changesete9ab1c4修复了action 权限条件permission condition未传value时抛错的问题——该修复让 Scaffolder 内置 action 在不配置具体权限值时也能正常工作避免模板执行因空值校验失败而中断。六、值得关注的 Patch 变更与升级注意事项6.1 缓存哈希算法升级MD5 → SHA-256FIPS 合规changesetb6b15b2同时作用于backstage/backend-common0.20.1与backstage/cli0.25.1缓存cache的哈希键计算从 MD5 改为SHA-256CLI 构建脚本的缓存键同样改用 SHA-256。副作用提示当原缓存键长度超过 250 字符时此次升级会使既有缓存失效需要重新预热/重建。其收益是提升对FIPS Node.js的合规性——在 FIPS 模式下运行 Backstage 后端与使用 CLI 构建时不再因 MD5 受限而失败。升级后首次构建/启动会较慢属正常现象。6.2 backend-common 其他修复changeset3b24eae新增从 git index 移除文件的支持changeset454d17c不再直接调用fetch改用fetchResponse工具封装统一响应处理链路changeset6878b1dcore-components / core-plugin-api移除history、immer、i18next等不再必要的依赖。6.3 新后端系统New Backend System全面加速v1.22.0 中新后端系统不再处于 alpha的信号非常明显changeset2e6c56b出现在多个 search 相关模块的说明文案中。具体落点包括catalog-backend-module-openapichangeset4ebf99b新增default导出可用新后端系统一行注册backend.add(import(backstage/plugin-catalog-backend-module-openapi));events-backend 系列模块changesetaf76a95events-backend-module-azure、bitbucket-cloud、gerrit等补充了default导出与新后端系统文档Microsoft / Pinniped 认证模块changeset928efbcauthModuleMicrosoftProvider、authModulePinnipedProvider具名导出被弃用改为默认导出推荐用法backend.add(import(backstage/plugin-auth-backend-module-microsoft-provider)); backend.add(import(backstage/plugin-auth-backend-module-pinniped-provider));auth-backendchangeset004499c修复 Okta 部分 resolver 缺失的问题。6.4 Catalog 与其他插件修复catalog-backendchangesetc3249d6URL 解析不再依赖git-url-parse改用其他解析方式以支持非 VCS 提供方的带通配符 URLcatalog-clientchangeset883782e修复getLocationByRef导致无效后端调用的问题repo-tools同步更新 OpenAPI 模板导出TypedResponse接口供客户端使用api-docschangeset8a69cc9/062b8f2修复 AsyncAPI widget 的自定义 http resolver并为 Register Existing API 按钮增加权限校验kuberneteschangesetd5d2c67GKE 集群链接加入authuser查询参数使 GCP 控制台自动切换到与 Backstage Google 登录相同的账号视图scaffolder-react表单顶部展示错误列表c28f281、默认展示第一条输出文本d16f85f、修复无属性 step0b9ce2buser-settingschangeset56b2fb0语言选择器改为优先显示原生语言名称而非语言代码并新增声明式集成导航项eea0849。6.5 升级建议先处理破坏性变更全仓搜索并替换app/router→app/root包括扩展配置与attachTo引用否则新前端系统应用启动失败关注缓存失效升级后首次 CLI 构建与后端缓存键计算将改用 SHA-256预构建镜像或 CI 缓存建议先清空重建替换弃用导出将 Microsoft/Pinniped 认证模块的具名导入改为默认导入利用app/root新能力OAuth 对话框、全局 Alert、自定义 Router 均可通过createAppRootElementExtension/createAppRootWrapperExtension/createRouterExtension声明式接入避免手写 App 包裹层尝鲜动态插件按上文backend-dynamic-feature-service的三种打包方案之一产出动态插件并配置dynamicPlugins.rootDirectory。七、总结v1.22.0 是 Backstage 架构演进路径上的一个标志性版本backend-dynamic-feature-service让后端插件首次具备运行时加载通道新前端系统的app/root扩展点重塑了应用根级组装方式而 SHA-256 缓存算法升级则为 FIPS 环境扫清了障碍。对于插件作者与平台维护者而言优先适配app/root重命名、跟进新后端系统default导出规范并评估动态插件打包方案是本次升级的三个主要行动项。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考