做微服务的人迟早会被配置优先级恶心一回。我之前排查过一个线上问题，明明在 Nacos 控制台把超时时间改成 5 秒了，服务跑起来还是 1 秒就超时，最后发现是本地 application.yml 里躺着一个同名配置，把 Nacos 里的值给盖住了。Nacos 配置中心和本地配置的优先级，看着是个小问题，真出故障时能把人折腾一整天。这篇文章就把这个事彻底讲清楚，包括加载顺序、覆盖规则、动态刷新的坑，以及一套随手能用的排查方案，适合正在用 Spring Cloud Alibaba + Nacos 管理配置、或者准备把配置往 Nacos 迁的团队参考。
1. 配置从哪来：Nacos 配置中心和本地配置的分工
1.1 本地配置文件都有哪些形态
本地配置最常见的载体是 Spring Boot 的 application.yml，但如果你用过 Spring Cloud，一定也见过 bootstrap.yml。这俩玩意儿看着像，作用完全不同。
application.yml 是业务配置落地的地方，端口、数据库地址、业务开关、日志级别，全往里面放。bootStrap.yml 是给 Spring Cloud 上下文做引导用的，在 application 上下文创建之前加载，主要负责拉取 Nacos 地址、服务名、加密解密这类“元配置”。Spring Cloud 2020.0.1 之后，bootstrap 默认被禁用，除非你显式引入 spring-cloud-starter-bootstrap 依赖，或者改用 spring.config.import 的方式加载 Nacos 配置。
除了这俩文件，本地配置还可能是 JVM 系统参数（-Dxxx）、环境变量、命令行参数。注意，这些外部输入的配置天然排在最高优先级，因为它们不是“配置文件”，而是运行环境直接塞给程序的。我们聊的“本地配置优先级”，实际主要是在说 application.yml / bootstrap.yml 和 Nacos 远程配置之间的博弈，但真要排查问题时，外部参数也得留个心眼。
1.2 Nacos 配置中心里那三层概念
Nacos 配置中心不是一坨配置平铺在那儿，它有三个层级：Namespace（命名空间）、Group（分组）、Data ID（数据 ID）。
Namespace 一般用来隔离环境，比如 dev、test、prod 各来一个命名空间，互不干扰。Group 在命名空间内部做二级分组，默认 DEFAULT_GROUP，如果你想区分订单服务、用户服务，可以把不同服务配置分到不同组。Data ID 是配置的最终名字，在 Spring Cloud Alibaba 里通常长这样：${spring.application.name}.${file-extension}，例如mall-user.yaml，还可以带 profile：mall-user-dev.yaml。
去 Nacos 控制台翻一下，配置列表就是这三层字段的组合。你写 spring.cloud.nacos.config.namespace 和 group 的时候，实际上就是在告诉客户端去哪个坐标捞配置。这个坐标体系很重要，因为后面聊优先级，离不开 dataId 的组织顺序。
1.3 为什么优先级这么让人头疼
按理说，有了配置中心，大家都把配置放远程不就行了？但实际项目里，本地配置不可能完全消灭。启动阶段就要用的数据源地址、密钥、以及 Nacos 服务器本身的信息，必须得在本地先有。而且很多人习惯把日志级别、开关参数留在本地，图的是改起来不用提交代码。
于是同一个 key 可能同时出现在本地 application.yml 和 Nacos 的某个 dataId 里。两边都定义了，听谁的？这就是优先级问题的来源。更要命的是，Spring Cloud Alibaba 不同版本、不同的加载方式（bootstrap 还是 spring.config.import），会导致结论不一样。网上搜答案，经常看到 A 说远程优先、B 说本地优先，其实他们说的都没错，但环境不同。
我个人的态度是：把优先级规则理解成一条“加载顺序加覆盖规则”的链条，而不是死记硬背某一条结论。下面我分几个层面把这条链拆开。
2. 核心结论：同名配置到底谁覆盖谁
2.1 先说结论：一个简单的优先级阶梯
以 Spring Boot 2.4+、Spring Cloud Alibaba 2021+、使用 spring.config.import 方式加载 Nacos 配置为例，我实测下来优先级从高到低大致是：
- 命令行参数、JVM 系统属性、环境变量
- Nacos 远程配置（带 profile 的应用配置 > 应用主配置 > 扩展配置 > 共享配置）
- 本地 application-{profile}.yml
- 本地 application.yml
这里最关键的一句话：在默认情况下，Nacos 里的配置会覆盖本地 application.yml 里的同名配置。这也是配置中心能成立的基础，如果你在 Nacos 改了超时时间，本地文件里藏着一个更优先的值，那改远程等于白改。
但注意，我说的是“默认情况下”。Spring Boot 2.4 之后，配置导入顺序其实遵循 ConfigData 的规则，Nacos 导入的配置是作为额外的 config data 加载进 Environment 的，加载的位置决定了优先级。虽然官方建议 Spring Cloud Config 作为高优先级导入，但 Nacos 客户端的行为在不同版本有细微差别。所以，如果你发现 Nacos 配置竟然没盖过本地，不要急着骂框架，先确认一下版本和加载方式。
2.2 Nacos 内部多个 dataId 的优先级排序
一个服务加载 Nacos 配置时，可能涉及多个 dataId。比如：
mall-user-dev.yaml（带 profile）mall-user.yaml（主配置）common.yaml（共享配置）rpc-ext.yaml（扩展配置）
它们之间也有优先级。根据 Spring Cloud Alibaba 的加载逻辑，按优先级从高到低排：
| 配置类别 | 示例 dataId | 优先级 |
|---|---|---|
| 应用配置带 profile | ${spring.application.name}-${profile}.yaml | 最高 |
| 应用主配置 | ${spring.application.name}.yaml | 其次 |
| extension-configs | 数组下标越靠后，优先级越高 | 再次 |
| shared-configs | 数组下标越靠后，优先级越高 | 最低 |
比如你在 shared-configs 里配了common.yaml，又在主配置mall-user.yaml里定义同一个 key，那mall-user.yaml的值会覆盖common.yaml。带 profile 的配置一般也是最高优先级，所以mall-user-dev.yaml能覆盖mall-user.yaml。
这个设计很合理：越通用的配置优先级越低，越贴近具体实例的配置优先级越高。你在 everyday 场景写死了 common 里的默认值，再在 profile 里针对某套环境覆盖一次，这才是配置中心的正确用法。
2.3 分组和命名空间会改变什么
如果你把 dataId 放在不同 group 或 namespace，优先级问题会变得微妙。
先说 namespace。不同 namespace 之间是完全隔离的，客户端一次连接只能指定一个 namespace（当然你可以通过多次 import 拉多个 namespace，但基本没人这么干）。所以 namespace 本身不参与“优先级排序”，它更多是选择集：你指定 dev 命名空间，拉到的就是 dev 的配置，拉不到 test 的。不存在 dev 和 test 谁覆盖谁。
group 就不一样了。同一个 dataId，放在 DEFAULT_GROUP 和放在 ORDER_GROUP，是两条不同的配置。如果你的扩展配置里引用了不同 group 的 dataId，优先级取决于数组顺序，而不是 group 名称。group 更像一个寻址条件，不是优先级条件。
2.4 几个反直觉的例外场景
优先级阶梯看着简单，实际坑不少。我列出几个反直觉的例外：
第一个是spring.profiles.active。这个 key 在远程 Nacos 里配置了，往往不生效。因为 Spring Boot 启动时，要先确定加载哪些 profile 的配置文件，这个动作发生在配置来源完整收集之前。你想通过 Nacos 把服务从 dev 切到 prod，基本没戏。正确做法是在本地配置里定 profile，或者通过启动参数--spring.profiles.active=prod显式指定。
第二个是spring.cloud.nacos.config.*这一坨元配置。这些配置必须在启动早期被读取，用来建立 Nacos 客户端连接，你没法把它们放 Nacos 里自己加载自己。本地 bootstrap.yml / application.yml 里必须留一份 Nacos 地址、命名空间、账号密码。这就涉及“启动引导配置靠本地，业务配置靠远程”的分工原则。
第三个是本地 application.yml 内部 multi-document 的优先级。Spring Boot 2.4 支持一个 yml 里用---分隔多段文档，后出现的文档优先级更高。如果本地文件里同一 key 写了两次，后面覆盖前面，这跟 Nacos 无关，但排查时容易干扰你。
第四个是配置文件外部化。使用spring.config.additional-location指定的外部配置文件，优先级可能高于 classpath 内部的 application.yml。如果你在 Nacos 之外还叠加了外部配置目录，那叫一个酸爽。我建议尽量减少配置来源的数量，来源越多，优先级排列组合越多，出问题越难查。
3. 手把手搭一个验证环境
3.1 准备一个 Spring Boot 微服务
理论说十遍，不如手跑一遍。我建议你也搞个最小的项目，把优先级行为钉死在自己熟悉的版本上。
环境准备：JDK 8+、Maven、一个可用的 Nacos Server（本地部署一个单机版即可，docker 一行命令docker run -p 8848:8848 -e MODE=standalone nacos/nacos-server:v2.2.3就能跑起来）。Spring Boot 用 2.7.x，Spring Cloud 用 2021.0.x，Spring Cloud Alibaba 用 2021.0.5.0，这套组合比较成熟，也贴近大多数公司的生产配置。
依赖上，只需要两块：
<dependency> <groupId>com.alibaba.cloud</groupId> <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId> </dependency> <dependency> <groupId>com.alibaba.cloud</groupId> <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId> </dependency>注意，因为用的是 spring.config.import 方式，不需要额外引入 bootstrap 依赖。如果想用老式 bootstrap 方式，才要加上spring-cloud-starter-bootstrap。
3.2 设计三组验证用例
我设计了三个场景，覆盖大多数生产问题：
场景 A：本地 application.yml 和 Nacos 主配置里有同一个 key，观察谁胜出。
场景 B：Nacos 里同时有共享配置 common.yaml 和应用主配置 mall-user.yaml，观察哪个覆盖哪个。
场景 C：本地 application.yml、应用主配置、带 profile 的应用配置三处都有同一个 key，观察最终值。
每个场景用一个业务 key，比如custom.timeout。为了快速看到结果，我写一个简单的 REST 接口返回当前值，然后启动时扫描 Environment 属性源顺序，把优先级打印出来。
验证服务代码很简单：
@RestController @RequestMapping("/config") public class ConfigController { @Value("${custom.timeout:default}") private String timeout; @GetMapping("/timeout") public String timeout() { return timeout; } }默认值default是为了防止没加载到配置时整个应用启动失败。
3.3 关键配置文件和 Nacos 数据准备
本地 application.yml 长这样：
spring: application: name: mall-user config: import: nacos:mall-user.yaml?group=DEFAULT_GROUP cloud: nacos: config: server-addr: 127.0.0.1:8848 namespace: dev file-extension: yaml shared-configs: ->@Component public class PropertySourcePrinter implements ApplicationRunner { @Override public void run(ApplicationArguments args) { ConfigurableEnvironment environment = ... ; environment.getPropertySources() .forEach(ps -> System.out.println(ps.getName())); } }日志里能看到 Nacos 的bootstrapProperties-mall-user-dev.yaml、bootstrapProperties-mall-user.yaml等属性源排在 application 属性源前面。属性源列表越靠前，优先级越高，这就直观地解释了为什么 Nacos 能覆盖本地。
4. 动态刷新和优先级配合的那些坑
4.1 @RefreshScope 是怎么实现热更新的
配置文件优先级解决了“启动时听谁的”，但生产上更关心“改完能不能热生效”。Nacos 配置中心之所以比改文件重启舒服，就是因为它支持配置动态刷新。
原理不复杂：Nacos 客户端会跟服务端建立一个长轮询，dataId 一旦发布新版本，服务端推送变更事件，客户端收到后会把对应 PropertySource 里的属性更新到 Spring Environment。接着 Spring Cloud 发布 RefreshEvent，所有被@RefreshScope标注的 Bean 会被标记为过期，下次访问时销毁重建，重新注入最新的属性值。
所以热更新的前提有两个：一是该配置所在的 dataId 在客户端声明的 refresh 标志为 true（shared/extension 配置尤其要注意，默认有没有开启 refresh 要看版本），二是使用配置的 Bean 必须挂在@RefreshScope下。两者缺一不可。
4.2 远程配置能刷新、本地配置为什么不行
本地配置文件是 classpath 里的静态资源，应用启动后它不会主动变化，也不参与 Nacos 的推送。所以存在在本地 application.yml 里的 key，无论你怎么改 Nacos，都刷新不了它，因为属性源根本没换。
这就衍生出一个很重要的实操原则：希望运行时动态调整的配置，尽量全部放到 Nacos 去，本地只留启动引导和兜底值。特别是线程池大小、超时时间、限流阈值、功能开关这一类高频调整项，放本地就是给自己埋雷。
另外有些配置即使放在 Nacos、也有 @RefreshScope，照样刷新不了。比如@ConfigurationProperties的 Bean，如果类上没有加@RefreshScope，属性变更后 Bean 不会重建。Spring Boot 的@ConfigurationProperties+@RefreshScope组合写起来有点绕，常见做法是在配置类上同时标@ConfigurationProperties(prefix = "custom")和@RefreshScope，但也要注意这两个注解的扫描顺序，实际项目里踩坑的人不少。
4.3 本地留了同名配置导致刷新不生效的典型案例
我之前遇到过一个典型故障：某个业务开关feature.flag配置在本地 application.yml 里，值是false。后来想通过 Nacos 动态打开开关，把值改成true，结果线上迟迟不生效。查了半天才发现，本地文件里这行最开始的兜底配置没人删，Nacos 的值尽管优先级更高，但在某些版本和加载方式下，本地的属性源反而压住了远程配置。
这种问题最坑的地方在于，它不一定必现。如果你用 bootstrap 方式引入 Nacos，有时 Nacos 属性源会插到更靠后的位置，导致本地配置胜出。对比下来你会发现，两个项目用不同 Spring Cloud Alibaba 版本，同样操作结果相反，最后只能靠日志和 env 端点确认。
处理方式很简单：全项目搜一遍同名 key，把本地残留删干净，或者用spring.cloud.nacos.config.override-none这类开关显式控制是否允许远程覆盖本地。但开关本身在不同版本里行为也有差异，最可靠的做法永远是删掉本地冗余配置，统一由 Nacos 管理。
4.4 多环境配置的最佳手法
命名空间天然适合做环境隔离。我会建 dev、test、prod 三个 namespace，每个 namespace 里放同一套 dataId 结构。本地 application.yml 里只选择当前环境的 namespace：
spring: cloud: nacos: config: namespace: ${NACOS_NAMESPACE:dev}打包部署不同环境时，通过环境变量 NACOS_NAMESPACE 覆盖。这样代码里不用写死环境名，也避免 profile 切换导致的配置串线。
环境相关但有差异的信息，比如数据库地址、日志级别，放到各自 namespace 的应用主配置里。环境无关的通用内容（例如通用的 Redis key 前缀规范）放到 shared-configs，common.yaml 在所有 namespace 都存在，但内容可以随环境不同而不同。这种做法的优点是结构清晰，缺点是每个环境都要维护 common.yaml，对配置管理规范要求比较高。团队小的时候，我更倾向于把通用配置直接塞进应用主配置里，少一层 shared 就少一层优先级纠缠。
5. 配置不生效时怎么排查
5.1 三步定位问题来源
遇到“改了 Nacos 但服务没变”这类问题，先别急着怀疑框架，按下面三步走：
第一步，确认你改的配置真的被加载了。打开服务启动日志，搜Located property source或者 Nacos 相关关键字，看有没有列出预期的 dataId、namespace、group。如果启动日志里压根没出现那个 dataId，说明寻址配置不对，后续优先级讨论无从谈起。
第二步，确认你这个 key 有没有被多个来源定义。用 Environment 端点或写临时代码打印属性源列表，重点是找到包含 key 的所有 PropertySource，然后看它们在列表里的排序。排序靠前的就是真正生效的来源。
第三步，确认动态刷新链路有没有断。如果启动能读到新值、运行时改 Nacos 不生效，检查 dataId 的 refresh 标志、@RefreshScope 是否齐全，以及监控客户端有没有收到推送。Nacos 控制台会显示客户端列表，可以从服务端视角确认连接是否正常。
5.2 用 Actuator 查看配置来源
Spring Boot Actuator 的 env 端点是查配置优先级的神器。首先确保引入了依赖：
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> </dependency>然后访问http://localhost:8080/actuator/env，会返回一个超级长的 JSON，里面按优先级列出了所有属性源和每个 key 的值。想只看某个 key 的值，用带路径的：
curl http://localhost:8080/actuator/env/custom.timeout返回结果里有一个propertySources数组，第一个就是当前最优值，后面是按优先级从高到低的各个来源。看到这里，基本能确定到底是 Nacos 赢了还是本地赢了。如果不想引 Actuator，也可以像我一样临时写个接口把 Environment 的 propertySources 遍历出来，效果类似。
5.3 常见问题速查表
| 症状 | 可能原因 | 解法 |
|---|---|---|
| Nacos 改了配置，服务重启后还是旧值 | 本地 application.yml 里有同名配置且优先级更高；或 namespace/group 没对上 | 删除本地同名配置；核对 namespace、group、dataId 三个坐标 |
| 启动时连不上 Nacos 导致启动失败 | spring.config.import 配置缺失或 server-addr 写错 | 本地显式声明 server-addr，并加上 spring.config.import |
| 运行时改配置不生效 | dataId 的 refresh 标志为 false；Bean 没加 @RefreshScope | 打开 refresh；补充 @RefreshScope |
| profile 切换不生效 | spring.profiles.active 写进了 Nacos 远程配置 | 移到本地配置或启动参数 |
| 控制台发布配置后客户端没反应 | Nacos 控制台没点发布按钮；或服务在另一个 namespace | 确认发布成功；检查 namespace 配置 |
| 多个 dataId 值互相干扰，最终值不符合预期 | 没搞清楚 extension/shared/主配置的优先级顺序 | 按第 2 节表格重新梳理 dataId 组织方式 |
排查配置问题，我最大的经验是别靠猜。所有覆盖关系在 Environment 里都是有据可查的，你只要能把 propertySources 打印出来，优先级就变成了一张明确的列表，谁高谁低一眼看清。很多团队遇到配置问题第一反应是改代码重启，浪费了大把时间。
最后再分享一个小技巧：每次接新项目或者升级 Spring Cloud Alibaba 版本时，花五分钟写一个临时接口打印一下属性源顺序，跑一次验证用例，把结论贴到团队文档里。版本升级后配置优先级行为很可能发生变化，这份实测记录能帮你少踩很多重复的坑。优先级这种事情，教科书说得再清楚，也不如你手上这一份跑出来的结果可靠。
