一、問題現(xiàn)象

在將 Spring Boot 2 升級到 Spring Boot 3 后，原本正常工作的 Nacos 配置熱更新功能失效。具體表現(xiàn)為：

1. 在 Nacos 控制臺修改配置字段值后，應用能收到配置變更通知，日志中出現(xiàn) Refresh keys changed: []
2. 但實際使用 @ConfigurationProperties 綁定的配置類（如 S3OssProperties）中的字段值仍然是舊值，未發(fā)生更新
3. 配置變更未能正確刷新到業(yè)務 Bean 中

二、原因分析

2.1 Nacos 熱更新的正常機制

在 Spring Cloud Alibaba 體系中，Nacos 配置熱更新的標準鏈路如下：

Nacos Server 
    ↓ (長輪詢推送)
Nacos Client 
    ↓ (回調(diào) Listener)
NacosContextRefresher 
    ↓ (發(fā)布 RefreshEvent)
RefreshEventListener 
    ↓ (調(diào)用 refreshAll())
RefreshScope 
    ↓ (銷毀緩存，重建 Bean)
@RefreshScope Bean → 使用新配置

Spring Boot 2.4.x 之后，Spring Cloud 引入了新的配置加載機制，通過 spring.config.import=nacos:... 方式引入 Nacos 配置源。在正確配置下，運行時刷新應走 ConfigDataContextRefresher 路徑。

2.2 問題定位：走錯刷新鏈路

通過日志和源碼追蹤發(fā)現(xiàn)，應用中實際走的是 LegacyContextRefresher 而非 ConfigDataContextRefresher。這說明：

• 應用雖然配置了 spring.config.import=nacos:...，啟動時能正常加載 Nacos 配置
• 但運行時的刷新機制落在了舊的 bootstrap 體系上
• 新的 Config Data 配置模型與舊的 Legacy 刷新鏈路發(fā)生了錯位

根本原因：項目中引入了 spring-cloud-starter-bootstrap 依賴，激活了舊的 bootstrap 上下文初始化機制。

2.3 Bootstrap 體系與 Config Data 體系的沖突

兩者的核心沖突在于：

• spring-cloud-starter-bootstrap 會強制啟用 Legacy 上下文刷新機制
• 而 spring.config.import 方式期望使用新的 ConfigData 機制
• 兩種機制并存時，Nacos 能收到配置變更事件，但 @ConfigurationProperties 的刷新綁定鏈路不完整

2.4 為什么會出現(xiàn)Refresh keys changed: []？

日志顯示 Refresh keys changed: [] 說明：

1. Nacos 客戶端確實收到了配置變更通知
2. NacosContextRefresher 也成功發(fā)布了 RefreshEvent 事件
3. 但在 LegacyContextRefresher.updateEnvironment() 處理過程中，未能正確識別出變更的配置項并觸發(fā) @ConfigurationProperties 的重綁定

最終表現(xiàn)為：配置文本已更新到 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 檢查并統(tǒng)一配置方式

確保配置文件統(tǒng)一使用 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 建議使用以下版本組合：

四、總結

本次問題的本質(zhì)是 配置管理體系的版本錯位：

• Spring Boot 3 默認采用新的 Config Data 配置模型（通過 spring.config.import）
• spring-cloud-starter-bootstrap 依賴強行激活了舊的 bootstrap/Legacy 刷新機制
• 兩種機制混用導致 Nacos 配置能收到變更但無法正確刷新 @ConfigurationProperties Bean

解決原則：在 Spring Boot 3 項目中，徹底移除 bootstrap 相關依賴，統(tǒng)一使用 spring.config.import 方式接入 Nacos 配置中心，確保刷新鏈路走 ConfigDataContextRefresher，從而實現(xiàn)配置熱更新的正常運作。

以上就是SpringBoot2升級到SpringBoot3后Nacos熱更新失效問題分析的詳細內(nèi)容，更多關于SpringBoot2升級到SpringBoot3后Nacos熱更新失效的資料請關注腳本之家其它相關文章！

最新評論