Spring Boot 2 升级到 Spring Boot 3 后 Nacos 热更新失效问题分析

文章目录

- 一、问题现象
- 二、原因分析
- - [2.1 Nacos 热更新的正常机制](#2.1 Nacos 热更新的正常机制)
  - [2.2 问题定位：走错刷新链路](#2.2 问题定位：走错刷新链路)
  - [2.3 Bootstrap 体系与 Config Data 体系的冲突](#2.3 Bootstrap 体系与 Config Data 体系的冲突)
  - [2.4 为什么会出现 `Refresh keys changed: []`？](#2.4 为什么会出现 Refresh keys changed: []？)
- 三、解决方案
- - [3.1 核心操作：移除 `spring-cloud-starter-bootstrap`](#3.1 核心操作：移除 spring-cloud-starter-bootstrap)
  - [3.2 检查并统一配置方式](#3.2 检查并统一配置方式)
  - [3.3 验证配置类注解正确性](#3.3 验证配置类注解正确性)
  - [3.4 配置验证清单](#3.4 配置验证清单)
  - [3.5 版本兼容性建议](#3.5 版本兼容性建议)
- 四、总结

一、问题现象

在将 Spring Boot 2 升级到 Spring Boot 3 后，原本正常工作的 Nacos 配置热更新功能失效。具体表现为：

在 Nacos 控制台修改配置字段值后，应用能收到配置变更通知，日志中出现 Refresh keys changed: []
但实际使用 @ConfigurationProperties 绑定的配置类（如 S3OssProperties）中的字段值仍然是旧值，未发生更新
配置变更未能正确刷新到业务 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 体系的冲突

特性	Bootstrap 体系（旧）	Config Data 体系（新）
触发方式	`spring-cloud-starter-bootstrap` 依赖	`spring.config.import` 配置
刷新实现	`LegacyContextRefresher`	`ConfigDataContextRefresher`
配置属性源	Bootstrap 属性源	ConfigData 属性源
Spring Boot 2.4+ 兼容性	需额外引入依赖	原生支持

两者的核心冲突在于：

spring-cloud-starter-bootstrap 会强制启用 Legacy 上下文刷新机制
而 spring.config.import 方式期望使用新的 ConfigData 机制
两种机制并存时，Nacos 能收到配置变更事件，但 @ConfigurationProperties 的刷新绑定链路不完整

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

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

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

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

三、解决方案

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

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

xml 复制代码

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

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

bash 复制代码

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

3.2 检查并统一配置方式

确保配置文件统一使用 application.yml 而非 bootstrap.yml，并采用 spring.config.import 方式引入 Nacos 配置：

yaml 复制代码

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 注解：

java 复制代码

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

3.4 配置验证清单

升级后的完整配置检查项：

检查项	状态	说明
移除 `spring-cloud-starter-bootstrap`	☐	避免 Legacy 刷新链路
使用 `application.yml` 替代 `bootstrap.yml`	☐	Spring Boot 3 推荐方式
`spring.config.import` 正确配置 Nacos	☐	含 `refreshEnabled=true`
`spring.cloud.nacos.config.refresh-enabled=true`	☐	显式开启刷新
`@ConfigurationProperties` 类有 `@RefreshScope`	☐	触发 Bean 重建
配置类包含 getter/setter	☐	属性注入必需

3.5 版本兼容性建议

Spring Boot 3.x 建议使用以下版本组合：

Spring Boot	Spring Cloud	Spring Cloud Alibaba
3.0.x - 3.2.x	2022.0.x	2022.0.0.1+

四、总结

本次问题的本质是 配置管理体系的版本错位：

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