尧图网站建设 
Backstage v1.30.0-next.2 预发布版本解读ConfigSources 修复、CLI 许可证支持与 Catalog Graph 实体呈现升级【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文基于 Backstage 仓库 docs/releases/v1.30.0-next.2-changelog.md 编写带你读懂该预发布版本pre-release中backstage/cli、backstage/plugin-catalog-graph等核心包的关键变更。你将掌握新版配置加载体系ConfigSources如何修复附加配置文件加载问题、backstage new命令如何设置包许可证以及目录图Catalog Graph节点标题与图标如何统一走entityPresentationApi呈现为后续升级到 v1.30.0 稳定版做好准备。一、版本概览一个面向稳定版的预发布快照v1.30.0-next.2是 Backstage 1.30.0 正式发布前的第二个预发布快照next 版本用于在正式发版前收集反馈与验证兼容性。其显著特点是变更聚焦、数量精简与常规 minor 版本相比本快照的实质代码变更集中在少数几个包上其余大量包仅因依赖版本号变化而同步 bump即“Updated dependencies”。版本序列明确本快照中各包的版本号都带有-next.2后缀如backstage/cli0.27.0-next.2并依赖一系列同样是 next 版本的库如backstage/config-loader1.9.0-next.1、backstage/integration1.14.0-next.0最终会汇聚到 1.30.0 正式版。本快照中发生实质代码变更的包只有三个包变更类型核心内容backstage/cli0.27.0-next.2Patch修复使用新ConfigSources时附加配置文件加载问题new命令新增设置包许可证能力backstage/create-app0.5.18-next.2Patch仅版本号 bump无代码逻辑变更backstage/plugin-catalog-graph0.4.8-next.2Patch节点标题与图标改用entityPresentationApi其余如example-app、example-app-next、e2e-test、techdocs-cli-embedded-app等均为示例/测试工程只同步更新依赖。二、backstage/cli修复新 ConfigSources 下的附加配置文件加载本次 CLI 最重要的一条修复是 commitb2d97fd修复使用新ConfigSources时加载附加配置文件additional config files的问题。2.1 背景从旧版 loadConfig 到 ConfigSources 的演进要理解这条修复需要先了解 Backstage 配置加载体系的演进。在旧版 API 中配置加载由packages/config-loader/src/loader.ts中的loadConfig函数承担。该文件源码中明确标注/** * public * deprecated Use {link ConfigSources.default} instead. */即loadConfig及其相关类型LoadConfigOptions、LoadConfigResult、ConfigTarget均已废弃官方推荐统一改用 packages/config-loader/src/sources/ConfigSources.ts 中新增的ConfigSources类。ConfigSources是一个配置源ConfigSource工具集合核心能力包括parseArgs(argv)解析命令行参数默认process.argv将--config path|url参数转换为配置目标列表实现上通过new URL(target)判断目标是本地路径还是远程 URL带主机名的视为 URL。defaultForTargets(options)为指定目标创建默认配置源。若未提供任何目标则回退到默认文件序列并按以下顺序读取详见源码ConfigSources.ts中defaultForTargets的实现app-config.yaml默认必需除非设置allowMissingDefaultConfig: trueBACKSTAGE_ENV环境变量指定的app-config.env.yaml多个值用逗号分隔app-config.local.yamlapp-config.env.local.yaml。其中 URL 目标仅在提供remote选项含reloadInterval重载间隔时才被支持否则会抛出 looks like a URL but remote configuration is not enabled 的错误。default(options)默认 Backstage 配置源在defaultForTargets基础上再叠加APP_CONFIG_前缀的环境变量源EnvConfigSource最终用merge合并为单一源。merge(sources)通过MergedConfigSource.from(sources)将多个配置源合并为一个串行读取的源。toConfig(source)将配置源转换为可关闭ClosableConfig的可观察配置实例读取一次后调用close()即可停止底层源的更新。2.2 修复点解读在旧版loadConfig时代CLI 通过configTargets显式接收附加配置文件路径列表。而切换到新的ConfigSources.defaultForTargets后附加配置文件的处理逻辑发生变化——defaultForTargets在无targets时会自动探测默认文件序列此时如果 CLI 传入的附加配置目标处理不当就会出现“附加配置文件未被正确加载”的回归问题。b2d97fd这条修复正是针对这一衔接问题确保使用新ConfigSources时通过--config传入的附加配置文件能够像旧版一样被完整加载并参与合并。从源码看defaultForTargets对每个target会创建对应的FileConfigSource本地路径或RemoteConfigSourceURL并通过watch选项支持文件监听热重载这正是新体系下“附加配置加载”的正确路径。2.3 升级影响与验证方式对使用默认配置布局app-config.yamlapp-config.local.yaml 环境变量的应用本修复无感知对通过--config extra.yaml或--config https://...注入附加配置的部署方式本修复保证了其在ConfigSources体系下的行为与旧版一致如需在代码中验证新体系可参考 packages/config-loader/src/sources/ConfigSources.test.ts 中的测试用例以及ConfigSources源码中的示例用法const sources ConfigSources.default({ argv }); const config await ConfigSources.toConfig(sources); config.close(); // 只读一次后立即关闭 const example config.getString(app.baseUrl);三、backstage/clibackstage new命令支持设置包许可证第二条 CLI 变更commitadabb40是new命令脚手架生成命令现在支持设置包的许可证license。backstage new是 Backstage CLI 的核心脚手架命令用于生成新的插件、后端模块、独立包等。此前生成的package.json中许可证字段由模板固定默认 Apache-2.0本次变更允许在命令执行过程中指定许可证类型生成的package.json会写入对应的license字段。这保证了企业或团队在生成新包时可以按照自身合规要求设置许可证而不必在生成后再手动修改package.json。该能力对应的命令交互流程为运行backstage new选择要生成的插件/包类型后新增的许可证选择/输入步骤会写入最终产物。具体命令选项与交互提示以当前 CLI 实际运行输出为准。四、backstage/plugin-catalog-graph节点标题与图标统一走 entityPresentationApi第三条实质变更commit4a529c2位于 plugins/catalog-graph 插件使用entityPresentationApi呈现节点标题title和图标icon。4.1 变更动机目录图插件Catalog Graph用于可视化目录实体Entity之间的依赖关系。此前图中节点的默认标题直接取自实体 ID图标来自固定的 kind 映射。而entityPresentationApi是 Backstage 前端的实体呈现抽象它允许插件/应用通过EntityPresentationApi自定义实体在不同场景下的展示形式标题、图标、颜色等从而保持全站一致的实体呈现体验。本次变更正是让 Catalog Graph 的默认节点渲染也接入这一抽象使节点显示与目录列表、实体页面等场景保持一致并允许通过自定义呈现实现如根据注解、所有权、自定义 kind 规则改变图中节点的标题与图标。4.2 源码级验证在默认节点渲染组件 plugins/catalog-graph/src/components/EntityRelationsGraph/DefaultRenderNode.tsx 中可以清晰看到这一实现const entityRefPresentationSnapshot useEntityPresentation(entity, { defaultNamespace: DEFAULT_NAMESPACE, }); const hasKindIcon !!entityRefPresentationSnapshot.Icon; // ... const displayTitle entityRefPresentationSnapshot.primaryTitle ?? id;关键点解读通过useEntityPresentation(entity, { defaultNamespace })获取实体呈现快照entityRefPresentationSnapshot节点的显示标题displayTitle取自primaryTitle仅在无法解析时回退到实体 ID节点的图标来自Icon字段entityRefPresentationSnapshot.Icon渲染时通过EntityIcon组件绘制在节点左侧节点 tooltip 的完整引用entityRefPresentationSnapshot.entityRef也来自同一快照。也就是说CatalogGraphPage与CatalogGraphCard组件中使用的节点渲染从此在标题与图标上全面遵循entityPresentationApi的约定任何自定义的实体呈现规则都会自动反映到目录图中。4.3 对使用者的影响默认行为不变不配置自定义呈现时节点仍显示实体标题与对应 kind 图标可定制性增强如果你的应用已经通过EntityPresentationApi定制了实体标题/图标例如按backstage.io/owned-by或自定义注解展示别名升级后这些定制会自动作用于目录图节点相关 API 依赖同步升级本变更同时提升了backstage/plugin-catalog-react1.12.3-next.1、backstage/core-plugin-api1.9.3、backstage/frontend-plugin-api0.6.8-next.1等依赖版本。五、示例与测试工程同步依赖更新本次快照中仓库内的示例与测试工程仅做依赖同步 bump无业务逻辑变更example-app / example-app-next覆盖 CLI、catalog-graph、scaffolder、search、techdocs、kubernetes、notifications 等全套插件的新版本依赖e2e-test同步backstage/create-app、cli-common、errors依赖techdocs-cli-embedded-app同步 CLI、app-defaults、core-app-api、plugin-techdocs 等依赖。这些同步更新保证了示例工程与各包新版本兼容便于开发者在升级后基于示例验证功能。六、升级建议与注意事项把握 next 版本定位v1.30.0-next.2是预发布快照适合在测试环境先行验证生产环境建议等待 1.30.0 正式版重点关注 CLI 与 catalog-graph本次实质变更集中在这两个包升级后建议重点回归使用--config附加配置文件启动前后端确认配置被正确加载与合并使用backstage new生成新包确认许可证字段正确写入打开目录图页面/卡片确认节点标题与图标显示正常尤其是已定制EntityPresentationApi的应用检查自定义配置加载代码如果你的代码仍在使用backstage/config-loader中废弃的loadConfigpackages/config-loader/src/loader.ts建议逐步迁移到ConfigSources.default以享受文件监听、远程配置重载等新能力。结语v1.30.0-next.2是一个小而精的预发布快照backstage/cli修复了新ConfigSources体系下附加配置文件的加载回归、为backstage new增加了许可证设置能力backstage/plugin-catalog-graph则完成了向entityPresentationApi的统一呈现迁移。理解这三条变更你就能在正式版发布时平滑升级并充分利用新版配置体系与实体呈现抽象带来的能力。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Backstage v1.30.0-next.2 预发布版本解读：ConfigSources 修复、CLI 许可证支持与 Catalog Graph 实体呈现升级
Backstage v1.30.0-next.2 预发布版本解读ConfigSources 修复、CLI 许可证支持与 Catalog Graph 实体呈现升级【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文基于 Backstage 仓库 docs/releases/v1.30.0-next.2-changelog.md 编写带你读懂该预发布版本pre-release中backstage/cli、backstage/plugin-catalog-graph等核心包的关键变更。你将掌握新版配置加载体系ConfigSources如何修复附加配置文件加载问题、backstage new命令如何设置包许可证以及目录图Catalog Graph节点标题与图标如何统一走entityPresentationApi呈现为后续升级到 v1.30.0 稳定版做好准备。一、版本概览一个面向稳定版的预发布快照v1.30.0-next.2是 Backstage 1.30.0 正式发布前的第二个预发布快照next 版本用于在正式发版前收集反馈与验证兼容性。其显著特点是变更聚焦、数量精简与常规 minor 版本相比本快照的实质代码变更集中在少数几个包上其余大量包仅因依赖版本号变化而同步 bump即“Updated dependencies”。版本序列明确本快照中各包的版本号都带有-next.2后缀如backstage/cli0.27.0-next.2并依赖一系列同样是 next 版本的库如backstage/config-loader1.9.0-next.1、backstage/integration1.14.0-next.0最终会汇聚到 1.30.0 正式版。本快照中发生实质代码变更的包只有三个包变更类型核心内容backstage/cli0.27.0-next.2Patch修复使用新ConfigSources时附加配置文件加载问题new命令新增设置包许可证能力backstage/create-app0.5.18-next.2Patch仅版本号 bump无代码逻辑变更backstage/plugin-catalog-graph0.4.8-next.2Patch节点标题与图标改用entityPresentationApi其余如example-app、example-app-next、e2e-test、techdocs-cli-embedded-app等均为示例/测试工程只同步更新依赖。二、backstage/cli修复新 ConfigSources 下的附加配置文件加载本次 CLI 最重要的一条修复是 commitb2d97fd修复使用新ConfigSources时加载附加配置文件additional config files的问题。2.1 背景从旧版 loadConfig 到 ConfigSources 的演进要理解这条修复需要先了解 Backstage 配置加载体系的演进。在旧版 API 中配置加载由packages/config-loader/src/loader.ts中的loadConfig函数承担。该文件源码中明确标注/** * public * deprecated Use {link ConfigSources.default} instead. */即loadConfig及其相关类型LoadConfigOptions、LoadConfigResult、ConfigTarget均已废弃官方推荐统一改用 packages/config-loader/src/sources/ConfigSources.ts 中新增的ConfigSources类。ConfigSources是一个配置源ConfigSource工具集合核心能力包括parseArgs(argv)解析命令行参数默认process.argv将--config path|url参数转换为配置目标列表实现上通过new URL(target)判断目标是本地路径还是远程 URL带主机名的视为 URL。defaultForTargets(options)为指定目标创建默认配置源。若未提供任何目标则回退到默认文件序列并按以下顺序读取详见源码ConfigSources.ts中defaultForTargets的实现app-config.yaml默认必需除非设置allowMissingDefaultConfig: trueBACKSTAGE_ENV环境变量指定的app-config.env.yaml多个值用逗号分隔app-config.local.yamlapp-config.env.local.yaml。其中 URL 目标仅在提供remote选项含reloadInterval重载间隔时才被支持否则会抛出 looks like a URL but remote configuration is not enabled 的错误。default(options)默认 Backstage 配置源在defaultForTargets基础上再叠加APP_CONFIG_前缀的环境变量源EnvConfigSource最终用merge合并为单一源。merge(sources)通过MergedConfigSource.from(sources)将多个配置源合并为一个串行读取的源。toConfig(source)将配置源转换为可关闭ClosableConfig的可观察配置实例读取一次后调用close()即可停止底层源的更新。2.2 修复点解读在旧版loadConfig时代CLI 通过configTargets显式接收附加配置文件路径列表。而切换到新的ConfigSources.defaultForTargets后附加配置文件的处理逻辑发生变化——defaultForTargets在无targets时会自动探测默认文件序列此时如果 CLI 传入的附加配置目标处理不当就会出现“附加配置文件未被正确加载”的回归问题。b2d97fd这条修复正是针对这一衔接问题确保使用新ConfigSources时通过--config传入的附加配置文件能够像旧版一样被完整加载并参与合并。从源码看defaultForTargets对每个target会创建对应的FileConfigSource本地路径或RemoteConfigSourceURL并通过watch选项支持文件监听热重载这正是新体系下“附加配置加载”的正确路径。2.3 升级影响与验证方式对使用默认配置布局app-config.yamlapp-config.local.yaml 环境变量的应用本修复无感知对通过--config extra.yaml或--config https://...注入附加配置的部署方式本修复保证了其在ConfigSources体系下的行为与旧版一致如需在代码中验证新体系可参考 packages/config-loader/src/sources/ConfigSources.test.ts 中的测试用例以及ConfigSources源码中的示例用法const sources ConfigSources.default({ argv }); const config await ConfigSources.toConfig(sources); config.close(); // 只读一次后立即关闭 const example config.getString(app.baseUrl);三、backstage/clibackstage new命令支持设置包许可证第二条 CLI 变更commitadabb40是new命令脚手架生成命令现在支持设置包的许可证license。backstage new是 Backstage CLI 的核心脚手架命令用于生成新的插件、后端模块、独立包等。此前生成的package.json中许可证字段由模板固定默认 Apache-2.0本次变更允许在命令执行过程中指定许可证类型生成的package.json会写入对应的license字段。这保证了企业或团队在生成新包时可以按照自身合规要求设置许可证而不必在生成后再手动修改package.json。该能力对应的命令交互流程为运行backstage new选择要生成的插件/包类型后新增的许可证选择/输入步骤会写入最终产物。具体命令选项与交互提示以当前 CLI 实际运行输出为准。四、backstage/plugin-catalog-graph节点标题与图标统一走 entityPresentationApi第三条实质变更commit4a529c2位于 plugins/catalog-graph 插件使用entityPresentationApi呈现节点标题title和图标icon。4.1 变更动机目录图插件Catalog Graph用于可视化目录实体Entity之间的依赖关系。此前图中节点的默认标题直接取自实体 ID图标来自固定的 kind 映射。而entityPresentationApi是 Backstage 前端的实体呈现抽象它允许插件/应用通过EntityPresentationApi自定义实体在不同场景下的展示形式标题、图标、颜色等从而保持全站一致的实体呈现体验。本次变更正是让 Catalog Graph 的默认节点渲染也接入这一抽象使节点显示与目录列表、实体页面等场景保持一致并允许通过自定义呈现实现如根据注解、所有权、自定义 kind 规则改变图中节点的标题与图标。4.2 源码级验证在默认节点渲染组件 plugins/catalog-graph/src/components/EntityRelationsGraph/DefaultRenderNode.tsx 中可以清晰看到这一实现const entityRefPresentationSnapshot useEntityPresentation(entity, { defaultNamespace: DEFAULT_NAMESPACE, }); const hasKindIcon !!entityRefPresentationSnapshot.Icon; // ... const displayTitle entityRefPresentationSnapshot.primaryTitle ?? id;关键点解读通过useEntityPresentation(entity, { defaultNamespace })获取实体呈现快照entityRefPresentationSnapshot节点的显示标题displayTitle取自primaryTitle仅在无法解析时回退到实体 ID节点的图标来自Icon字段entityRefPresentationSnapshot.Icon渲染时通过EntityIcon组件绘制在节点左侧节点 tooltip 的完整引用entityRefPresentationSnapshot.entityRef也来自同一快照。也就是说CatalogGraphPage与CatalogGraphCard组件中使用的节点渲染从此在标题与图标上全面遵循entityPresentationApi的约定任何自定义的实体呈现规则都会自动反映到目录图中。4.3 对使用者的影响默认行为不变不配置自定义呈现时节点仍显示实体标题与对应 kind 图标可定制性增强如果你的应用已经通过EntityPresentationApi定制了实体标题/图标例如按backstage.io/owned-by或自定义注解展示别名升级后这些定制会自动作用于目录图节点相关 API 依赖同步升级本变更同时提升了backstage/plugin-catalog-react1.12.3-next.1、backstage/core-plugin-api1.9.3、backstage/frontend-plugin-api0.6.8-next.1等依赖版本。五、示例与测试工程同步依赖更新本次快照中仓库内的示例与测试工程仅做依赖同步 bump无业务逻辑变更example-app / example-app-next覆盖 CLI、catalog-graph、scaffolder、search、techdocs、kubernetes、notifications 等全套插件的新版本依赖e2e-test同步backstage/create-app、cli-common、errors依赖techdocs-cli-embedded-app同步 CLI、app-defaults、core-app-api、plugin-techdocs 等依赖。这些同步更新保证了示例工程与各包新版本兼容便于开发者在升级后基于示例验证功能。六、升级建议与注意事项把握 next 版本定位v1.30.0-next.2是预发布快照适合在测试环境先行验证生产环境建议等待 1.30.0 正式版重点关注 CLI 与 catalog-graph本次实质变更集中在这两个包升级后建议重点回归使用--config附加配置文件启动前后端确认配置被正确加载与合并使用backstage new生成新包确认许可证字段正确写入打开目录图页面/卡片确认节点标题与图标显示正常尤其是已定制EntityPresentationApi的应用检查自定义配置加载代码如果你的代码仍在使用backstage/config-loader中废弃的loadConfigpackages/config-loader/src/loader.ts建议逐步迁移到ConfigSources.default以享受文件监听、远程配置重载等新能力。结语v1.30.0-next.2是一个小而精的预发布快照backstage/cli修复了新ConfigSources体系下附加配置文件的加载回归、为backstage new增加了许可证设置能力backstage/plugin-catalog-graph则完成了向entityPresentationApi的统一呈现迁移。理解这三条变更你就能在正式版发布时平滑升级并充分利用新版配置体系与实体呈现抽象带来的能力。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考