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/cli@0.27.0-next.2），并依赖一系列同样是 next 版本的库（如@backstage/config-loader@1.9.0-next.1、@backstage/integration@1.14.0-next.0），最终会汇聚到 1.30.0 正式版。

本快照中发生实质代码变更的包只有三个：

其余如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的实现）：

  1. app-config.yaml（默认必需，除非设置allowMissingDefaultConfig: true）；
  2. BACKSTAGE_ENV环境变量指定的app-config.<env>.yaml（多个值用逗号分隔）；
  3. app-config.local.yaml；
  4. app-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（本地路径）或RemoteConfigSource（URL），并通过watch选项支持文件监听热重载，这正是新体系下“附加配置加载”的正确路径。

2.3 升级影响与验证方式

• 对使用默认配置布局（app-config.yaml+app-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/cli：backstage 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-react@1.12.3-next.1、@backstage/core-plugin-api@1.9.3、@backstage/frontend-plugin-api@0.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 等依赖。

这些同步更新保证了示例工程与各包新版本兼容，便于开发者在升级后基于示例验证功能。

六、升级建议与注意事项

1. 把握 next 版本定位：v1.30.0-next.2是预发布快照，适合在测试环境先行验证，生产环境建议等待 1.30.0 正式版；
2. 重点关注 CLI 与 catalog-graph：本次实质变更集中在这两个包，升级后建议重点回归：
   • 使用--config附加配置文件启动前后端，确认配置被正确加载与合并；
   • 使用backstage new生成新包，确认许可证字段正确写入；
   • 打开目录图页面/卡片，确认节点标题与图标显示正常（尤其是已定制EntityPresentationApi的应用）；
3. 检查自定义配置加载代码：如果你的代码仍在使用@backstage/config-loader中废弃的loadConfig（packages/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