Nacos 新版配置指南（Spring Cloud Alibaba 2023.x）
适用版本：Spring Boot 3.2.x + Spring Cloud 2023.0.3 + Spring Cloud Alibaba 2023.0.3.2
一、新版与旧版的核心区别
| 对比项 | 旧版（bootstrap 机制） | 新版（2023.x） |
|---|---|---|
| 配置加载入口 | bootstrap.yml+spring-cloud-starter-bootstrap | application.yml+spring.config.import |
| 配置中心依赖 | 必须引入spring-cloud-starter-bootstrap | 无需 bootstrap 依赖，原生 Config Data 机制 |
| 不存在配置时 | 直接启动失败 | 支持optional:前缀优雅降级 |
二、新版配置写法
1. 标准写法
server:port:8083spring:application:name:system-servicecloud:nacos:server-addr:192.168.145.132:8848# 顶层公共属性，discovery 和 config 共享discovery:namespace:simple-devconfig:namespace:simple-devfile-extension:ymlconfig: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. 相关开关一览
| 配置项 | 默认值 | 说明 |
|---|---|---|
spring.cloud.nacos.config.override-none | false | true= Nacos 不覆盖本地已存在的属性 |
spring.cloud.nacos.config.allow-override | true | false= Nacos 强制优先，任何本地配置都无法覆盖 |
spring.cloud.nacos.config.override-system-properties | false | true= Nacos 可覆盖 JVM 系统属性（-D参数） |
注意：
override-none在旧的 bootstrap 机制下需要在Nacos 服务端配置才生效；在新版spring.config.import机制下，写在客户端本地application.yml即可生效。
四、动态刷新
importURL 加参数：optional:nacos:${spring.application.name}.yml?refreshEnabled=true（或在config下设置refresh-enabled: true，默认开启）。- 需要运行时刷新的 Bean 加
@RefreshScope；@ConfigurationProperties绑定的类天然支持刷新。 @Value注入的属性必须配合@RefreshScope才能刷新。
五、官方参考链接
| 资料 | 链接 |
|---|---|
| Issue #3998：2023.0.1.3+ 版本接入 Nacos 配置中心参数兼容性问题说明（官方） | https://github.com/alibaba/spring-cloud-alibaba/issues/3998 |
Issue #3915：新版serverAddr公共配置 +spring.config.import写法（官方维护者回复） | https://github.com/alibaba/spring-cloud-alibaba/issues/3915 |
Issue #3943：server-addr报 serverAddr=null（地址格式/缩进错误） | https://github.com/alibaba/spring-cloud-alibaba/issues/3943 |
Issue #3969：同类问题，NacosDiscoveryProperties.serverAddr为 null | https://github.com/alibaba/spring-cloud-alibaba/issues/3969 |
| 官方文档（2023.x 中文）Nacos Config 进阶指南 | https://github.com/spring-cloud-alibaba-group/spring-cloud-alibaba-group.github.io/blob/main/src/content/docs/2023/zh-cn/user-guide/nacos/advanced-guide.md |
| Spring Cloud Alibaba 官网首页 | https://sca.aliyun.com/ |
六、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.yml3. 已废弃（需迁移）的旧方式
| 旧方式 | 说明 |
|---|---|
spring.application.name+file-extension拼接 | 最初版本按应用名自动拼接 dataId |
share-configs | 共享配置导入 |
extension-configs | 扩展配置导入 |
以上方式在 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 连接池运行期无损轮转
注意事项
- 部分内容由AI生成
- 如有不对，欢迎指正！！！
