SpringBoot2升级到SpringBoot3后Nacos热更新失效问题分析

一、问题现象

不少团队在将应用从 Spring Boot 2 升级到 Spring Boot 3 后，遇到了一个颇为棘手的问题：原本运行良好的 Nacos 配置热更新功能，突然就“罢工”了。

具体表现通常很一致：

1. 在 Nacos 控制台修改了某个配置项的值，应用确实能收到变更通知，日志里也会出现 Refresh keys changed: [] 这样的记录。
2. 但尴尬的是，实际业务代码里，那些用 @ConfigurationProperties 绑定的配置类（比如 S3OssProperties），里面的字段值依然是“老黄历”，纹丝不动。
3. 结果就是，配置变更的通知虽然到了，但新值却没能成功刷新到业务 Bean 里，热更新名存实亡。

二、原因分析

2.1 Nacos 热更新的正常机制

要搞清楚问题出在哪，得先明白在 Spring Cloud Alibaba 这套体系里，配置热更新的标准流程是怎么走的。理想情况下，链路应该是这样的：

Nacos Server 
    ↓ (长轮询推送)
Nacos Client 
    ↓ (回调 Listener)
NacosContextRefresher 
    ↓ (发布 RefreshEvent)
RefreshEventListener 
    ↓ (调用 refreshAll())
RefreshScope 
    ↓ (销毁缓存，重建 Bean)
@RefreshScope Bean → 使用新配置

这里有个关键点需要注意：从 Spring Boot 2.4.x 开始，Spring Cloud 引入了一套全新的配置加载机制，核心就是通过 spring.config.import=nacos:... 这种方式来引入 Nacos 配置源。如果一切配置正确，运行时刷新就应该走 ConfigDataContextRefresher 这条新路径。

2.2 问题定位：走错刷新链路

然而，通过分析问题应用的日志和追踪源码，你会发现实际情况并非如此。应用在收到配置变更后，实际走的是 LegacyContextRefresher 这条旧路，而不是期望的 ConfigDataContextRefresher。

这说明了什么？

• 应用启动时，通过 spring.config.import=nacos:... 确实能正常加载 Nacos 的配置。
• 但到了运行时刷新这一步，机制却“掉队”了，落回到了旧的 bootstrap 体系里。
• 简单说，就是新的 Config Data 配置模型和旧的 Legacy 刷新链路发生了错位，两者没对上号。

那么，根本原因是什么？ 排查下来，十有八九是因为项目中引入了 spring-cloud-starter-bootstrap 这个依赖。它就像一个“开关”，强行激活了旧的 bootstrap 上下文初始化机制，把刷新流程给带偏了。

2.3 Bootstrap 体系与 Config Data 体系的冲突

这两套机制的核心冲突在于：

• spring-cloud-starter-bootstrap 会强制启用 Legacy 上下文刷新机制。
• 而 spring.config.import 这种方式，期望的是使用新的 ConfigData 机制。
• 当两种机制在同一个应用里并存时，就会导致混乱：Nacos 客户端能收到配置变更事件，但 @ConfigurationProperties 的刷新绑定链路却断了，无法完成最后一步。

2.4 为什么会出现Refresh keys changed: []？

这行日志很关键，它揭示了问题的中间状态：

1. 首先，它证明 Nacos 客户端确实收到了配置变更通知，消息传递链路前半截是通的。
2. 其次，NacosContextRefresher 也成功发布了 RefreshEvent 事件。
3. 问题出在最后一步：LegacyContextRefresher.updateEnvironment() 在处理过程中，没能正确识别出哪些配置项发生了变更，自然也就无法触发 @ConfigurationProperties 的重新绑定（rebind）。

所以最终你看到的现象就是：配置的文本内容其实已经更新到 Environment 里了，但依赖这些配置的 @ConfigurationProperties Bean 却没有被重建，里面的字段值当然还是旧的。

三、解决方案

3.1 核心操作：移除spring-cloud-starter-bootstrap

解决问题的第一步，也是最关键的一步，就是清理掉那个“捣乱”的依赖。在 Ma ven 项目中，请检查并移除它：

    org.springframework.cloud
    spring-cloud-starter-bootstrap

如果不确定是哪个间接依赖引入了它，可以用 Ma ven 命令来排查：

mvn dependency:tree | grep spring-cloud-starter-bootstrap

3.2 检查并统一配置方式

确保你的配置文件统一使用 application.yml（或 application.properties），而不是旧的 bootstrap.yml。同时，采用标准的 spring.config.import 方式来引入 Nacos 配置源：

spring:
  config:
    import: optional:nacos:${nacos.config.data-id}.${nacos.config.file-extension}?group=${nacos.config.group}&refreshEnabled=true
  cloud:
    nacos:
      config:
        server-addr: ${NACOS_SERVER_ADDR:localhost:8848}
        refresh-enabled: true  # 在 Spring Boot 3 中，建议显式开启此选项

3.3 验证配置类注解正确性

确保你的配置类在使用了 @ConfigurationProperties 的同时，也加上了 @RefreshScope 注解。这是触发 Bean 重建的必要条件：

@Component
@RefreshScope
@ConfigurationProperties(prefix = "oss.s3")
public class S3OssProperties {
    private String endpoint;
    private String bucket;
    // 别忘了，getter和setter方法必须存在
}

3.4 配置验证清单

升级完成后，建议按照下面这个清单逐一核对，确保每个环节都已就位：

3.5 版本兼容性建议

为了确保整个技术栈的稳定性，在 Spring Boot 3.x 环境下，建议采用以下经过验证的版本组合：

四、总结

回顾一下，这次问题的本质其实是 配置管理体系的版本错位 导致的：

• Spring Boot 3 默认拥抱了新的 Config Data 配置模型（通过 spring.config.import）。
• 而项目中遗留的 spring-cloud-starter-bootstrap 依赖，却强行把刷新机制拉回到了旧的 bootstrap/Legacy 路径。
• 新旧两套机制混用，直接结果就是 Nacos 配置变更通知能收到，但 @ConfigurationProperties Bean 的刷新绑定链路断了，热更新功能自然失效。

最终的解决原则很清晰：在 Spring Boot 3 项目中，应当彻底告别旧的 bootstrap 体系。移除相关依赖，统一使用 spring.config.import 方式来接入 Nacos 等配置中心。这样才能确保配置刷新走正确的 ConfigDataContextRefresher 链路，让热更新功能恢复正常运作。