一、問(wèn)題現(xiàn)象

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

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

二、原因分析

2.1 Nacos 熱更新的正常機(jī)制

在 Spring Cloud Alibaba 體系中，Nacos 配置熱更新的標(biāo)準(zhǔn)鏈路如下：

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

Spring Boot 2.4.x 之后，Spring Cloud 引入了新的配置加載機(jī)制，通過(guò) spring.config.import=nacos:... 方式引入 Nacos 配置源。在正確配置下，運(yùn)行時(shí)刷新應(yīng)走 ConfigDataContextRefresher 路徑。

2.2 問(wèn)題定位：走錯(cuò)刷新鏈路

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

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

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

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

兩者的核心沖突在于：

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

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

日志顯示 Refresh keys changed: [] 說(shuō)明：

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

最終表現(xiàn)為：配置文本已更新到 Environment 中，但 @ConfigurationProperties Bean 未重建，字段值仍為舊值。

三、解決方案

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

在 Maven 項(xiàng)目中檢查并移除該依賴：

<!-- 移除此依賴 -->
<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 驗(yàn)證配置類注解正確性

確保使用 @ConfigurationProperties 的配置類同時(shí)添加了 @RefreshScope 注解：

@Component
@RefreshScope
@ConfigurationProperties(prefix = "oss.s3")
public class S3OssProperties {
    private String endpoint;
    private String bucket;
    // getter/setter 必須存在
}

3.4 配置驗(yàn)證清單

升級(jí)后的完整配置檢查項(xiàng)：

3.5 版本兼容性建議

Spring Boot 3.x 建議使用以下版本組合：

四、總結(jié)

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

• Spring Boot 3 默認(rèn)采用新的 Config Data 配置模型（通過(guò) spring.config.import）
• spring-cloud-starter-bootstrap 依賴強(qiáng)行激活了舊的 bootstrap/Legacy 刷新機(jī)制
• 兩種機(jī)制混用導(dǎo)致 Nacos 配置能收到變更但無(wú)法正確刷新 @ConfigurationProperties Bean

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

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

最新評(píng)論