Nacos 新版配置指南（Spring Cloud Alibaba 2023.x）

Nacos 新版配置指南（Spring Cloud Alibaba 2023.x）

适用版本：Spring Boot 3.2.x + Spring Cloud 2023.0.3 + Spring Cloud Alibaba 2023.0.3.2

一、新版与旧版的核心区别

二、新版配置写法

1. 标准写法

server:
  port: 8083

spring:
  application:
    name: system-service
  cloud:
    nacos:
      server-addr: 192.168.145.132:8848      # 顶层公共属性，discovery 和 config 共享
      discovery:
        namespace: simple-dev
      config:
        namespace: simple-dev
        file-extension: yml
  config:
    import:
      - optional:nacos:${spring.application.name}.yml

要点说明：

• spring.cloud.nacos.server-addr 放在 nacos 顶层，作为公共默认值，discovery 和 config 都会继承；若各自下面单独配置，则覆盖公共值。
• spring.config.import 是新版加载 Nacos 配置的唯一入口，optional: 前缀表示 Nacos 上没有该配置文件时不报错、正常启动。
• import 支持 URL 参数：nacos:dataId?refreshEnabled=true&group=DEFAULT_GROUP。

三、配置覆盖逻辑（本地 vs Nacos）

1. 默认行为：Nacos 覆盖本地

• 启动阶段：spring.config.import 中后导入的 PropertySource 优先级高，Nacos 配置覆盖本地 application.yml 同名属性。
• 运行阶段：Nacos 配置变更推送后（动态刷新），Nacos 的 PropertySource 会重新以高优先级插入 Environment，本地同名属性持续被覆盖。import 顺序只在启动瞬间有效，无法阻止运行时覆盖。

2. 让本地覆盖 Nacos：override-none: true

spring:
  cloud:
    nacos:
      config:
        override-none: true

• 含义：本地已存在的属性，Nacos 不覆盖；本地没有的属性，由 Nacos 补充。
• 启动阶段和运行时动态刷新两个阶段都生效，这是唯一可靠的"本地优先"方案。

3. 相关开关一览

注意：override-none 在旧的 bootstrap 机制下需要在 Nacos 服务端配置才生效；在新版 spring.config.import 机制下，写在客户端本地 application.yml 即可生效。

四、动态刷新

1. import URL 加参数：optional:nacos:${spring.application.name}.yml?refreshEnabled=true（或在 config 下设置 refresh-enabled: true，默认开启）。
2. 需要运行时刷新的 Bean 加 @RefreshScope；@ConfigurationProperties 绑定的类天然支持刷新。
3. @Value 注入的属性必须配合 @RefreshScope 才能刷新。

五、官方参考链接

六、2023.0.1.3+ 版本不兼容说明（官方 Issue #3998）

官方说明：https://github.com/alibaba/spring-cloud-alibaba/issues/3998
适用场景：升级到 2023.0.1.3 及以上版本时

1. 背景

2023.0.1.3+ 版本对 Nacos 配置中心接入方式做了不兼容变更，官方说明中对升级过程中遇到的兼容性问题进行了致歉，并明确了标准用法。

2. 统一标准用法：spring.config.import

导入单个配置：

spring:
  config:
    import: nacos:example.yml

导入多个配置：

spring:
  config:
    import:
      - nacos:example.yml
      - nacos:example2.yml

3. 已废弃（需迁移）的旧方式

以上方式在 2023.0.1.3+ 中已被删除，需统一迁移到 spring.config.import。

4. 模块拆分

2023.0.1.3 将 spring-cloud-starter-alibaba-nacos-config 拆分为：

• spring-alibaba-nacos-config：仅依赖 Spring Boot，支持在非 Spring Cloud 应用中独立使用
• spring-cloud-starter-alibaba-nacos-config：仅保留依赖 Spring Cloud 的组件

5. 新能力

• 新增 @NacosConfig、@NacosConfigListener 注解，提供配置注入与变更回调能力
• 2023.0.3.3 版本支持 Druid 连接池运行期无损轮转

注意事项

1. 部分内容由AI生成
2. 如有不对，欢迎指正！！！