Backstage(Spotify)：新增变量在app-config.yaml中无法被识别

核心结论 #

更新app-config文件后，必须重启前端服务（开发环境）或重新构建部署（生产环境），前端才能获取到新增的配置项。

原因说明 #

• 前端服务启动时会把配置文件内容加载到内存中运行，现有配置项的覆盖可能触发局部热重载，但新增的配置项不在初始加载的配置结构里，热重载机制无法自动识别并加载。
• backstage-cli config:print --frontend --config app-config.yaml是直接读取配置文件内容，所以能显示新增变量，但前端服务内存中并未加载该新项。

具体操作步骤 #

• 开发环境：修改配置文件后，停止当前运行的backstage-cli dev命令，重新启动即可。
• 生产环境：执行backstage-cli build重新构建前端应用，然后部署新版本；如果用容器化部署，需重新构建镜像并启动容器实例。

额外排查点 #

• 确认新增配置项未被标记为后端专属：如果配置项放在backend:字段下，或者未在app-config.yaml的frontend.allowedKeys中声明，前端将无法读取。前端可访问的配置需放在顶层非backend区域，或添加到frontend.allowedKeys白名单。
• 检查插件中读取配置的路径是否正确：比如新增变量为custom.myFeature.enabled，需确保用configApiRef.get('custom.myFeature.enabled')读取，路径错误会导致读取失败。

内容的提问来源于stack exchange，提问作者Pedro Henrique