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 配置热更新的标准链路如下：

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: []？

日志显示 Refresh keys changed: [] 说明：

1. Nacos 客户端确实收到了配置变更通知
2. NacosContextRefresher 也成功发布了 RefreshEvent 事件
3. 但在 LegacyContextRefresher.updateEnvironment() 处理过程中，未能正确识别出变更的配置项并触发 @ConfigurationProperties 的重绑定

最终表现为：配置文本已更新到 Environment 中，但 @ConfigurationProperties Bean 未重建，字段值仍为旧值。

三、解决方案

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

在 Maven 项目中检查并移除该依赖：

<!-- 移除此依赖 -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-bootstrap</artifactId>
</dependency>

使用 Maven 命令排查依赖引入路径：

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

3.2 检查并统一配置方式

确保配置文件统一使用 application.yml 而非 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 注解：

@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，从而实现配置热更新的正常运作。

以上就是SpringBoot2升级到SpringBoot3后Nacos热更新失效问题分析的详细内容，更多关于SpringBoot2升级到SpringBoot3后Nacos热更新失效的资料请关注脚本之家其它相关文章！