Spring Boot 整合 Nacos 配置中心（动态配置刷新 + 多环境配置）

你想要掌握 Spring Boot 项目如何整合 Nacos 配置中心，核心实现配置动态刷新（修改 Nacos 配置无需重启服务）和多环境配置管理（区分开发 / 测试 / 生产环境），这篇教程会从「环境准备→代码编写→测试验证」全程实操，基于最新稳定版本，新手也能一步到位。

前置准备

1. 环境要求

• JDK 8+（推荐 1.8）
• Maven 3.6+
• Nacos 2.x 稳定版（如 2.3.0/2.4.0，已启动并可访问控制台）
• Spring Boot 2.7.x（和 Spring Cloud Alibaba 版本匹配，避免冲突）

2. 版本匹配（关键！避免踩坑）

Spring Boot 和 Spring Cloud Alibaba 的版本必须对应，以下是经过验证的稳定组合：

表格

步骤 1：创建 Spring Boot 项目并引入依赖

1.1 新建 Maven 项目（或 Spring Initializr）

在pom.xml中引入核心依赖，重点是nacos-config-spring-boot-starter（Nacos 配置中心核心依赖）：

xml

<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.7.15</version> <relativePath/> </parent> <groupId>com.example</groupId> <artifactId>nacos-config-demo</artifactId> <version>1.0.0</version> <name>nacos-config-demo</name> <dependencies> <!-- Spring Boot Web Starter（提供接口测试） --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- Nacos 配置中心 Starter（核心依赖） --> <dependency> <groupId>com.alibaba.boot</groupId> <artifactId>nacos-config-spring-boot-starter</artifactId> <version>0.2.12</version> <!-- 排除内置的低版本nacos-client，避免冲突 --> <exclusions> <exclusion> <groupId>com.alibaba.nacos</groupId> <artifactId>nacos-client</artifactId> </exclusion> </exclusions> </dependency> <!-- 适配Nacos 2.x的客户端版本 --> <dependency> <groupId>com.alibaba.nacos</groupId> <artifactId>nacos-client</artifactId> <version>2.3.0</version> </dependency> <!-- lombok（简化代码，可选） --> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <optional>true</optional> </dependency> <!-- 测试依赖 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> <configuration> <excludes> <exclude> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> </exclude> </excludes> </configuration> </plugin> </plugins> </build> </project> 

步骤 2：Nacos 控制台配置多环境配置集

先在 Nacos 控制台创建开发（dev）、测试（test）、生产（prod） 三个环境的配置，后续项目可动态切换。

2.1 创建命名空间（环境隔离，核心！）

1. 打开 Nacos 控制台（http://127.0.0.1:8848/nacos，账号密码：nacos/nacos）；
2. 左侧菜单「命名空间」→「新建命名空间」：
   • 开发环境：名称dev，描述开发环境，自动生成命名空间 ID（如dev-123，记下来！）；
   • 测试环境：名称test，描述测试环境，命名空间 ID（如test-456）；
   • 生产环境：名称prod，描述生产环境，命名空间 ID（如prod-789）；
   • 注：默认命名空间 ID 为public，建议不用，专用于环境隔离。

2.2 编写各环境配置集

以「开发环境（dev）」为例，创建配置集：

1. 左侧菜单「配置管理→配置列表」→ 顶部选择dev命名空间 →「+」；
2. 配置信息：
   • Data ID：nacos-config-demo.yml（建议和项目名一致，后缀.yml/properties）；
   • Group：DEFAULT_GROUP（默认分组，也可自定义如GROUP_DEMO）；
   • 配置格式：YAML；
3. 点击「发布」，完成开发环境配置创建。

配置内容：yaml

# 开发环境配置 server: port: 8081 # 开发环境端口 demo: name: "开发环境-测试名称" desc: "这是开发环境的动态配置" 

同理，创建test/prod命名空间的配置集：

生产环境（prod）配置内容：yaml

server: port: 8083 demo: name: "生产环境-测试名称" desc: "这是生产环境的动态配置" 

测试环境（test）配置内容：yaml

server: port: 8082 demo: name: "测试环境-测试名称" desc: "这是测试环境的动态配置" 

步骤 3：项目配置文件编写（连接 Nacos + 指定环境）

在项目resources目录下创建application.yml，配置 Nacos 连接信息和默认环境：

yaml

# Spring Boot 核心配置 spring: application: name: nacos-config-demo # 应用名，和Nacos的Data ID前缀一致 # Nacos 配置中心配置 nacos: config: server-addr: 127.0.0.1:8848 # Nacos服务端地址（单机），集群写多个如127.0.0.1:8848,127.0.0.1:8849 namespace: dev-123 # 要连接的命名空间ID（dev环境，可切换为test-456/prod-789） group: DEFAULT_GROUP # 配置分组，和Nacos控制台一致 data-id: nacos-config-demo.yml # 配置集ID，和Nacos控制台一致 type: YAML # 配置格式，和Nacos控制台一致 refresh-enabled: true # 开启配置自动刷新（关键！） 

步骤 4：实现动态配置刷新（核心功能）

Nacos 配置中心的核心优势是「动态刷新」，修改 Nacos 配置后无需重启服务，有两种常用实现方式，推荐第一种（简单易用）。

4.1 方式 1：@RefreshScope 注解（推荐）

创建DemoController，通过@Value注入 Nacos 配置，并添加@RefreshScope实现动态刷新：

java

运行

package com.example.controller; import org.springframework.beans.factory.annotation.Value; import org.springframework.cloud.context.config.annotation.RefreshScope; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; /** * 测试动态配置刷新和多环境配置 */ @RestController @RefreshScope // 核心注解：开启配置刷新，修改Nacos配置后自动更新 public class DemoController { // 注入Nacos中的配置项 @Value("${demo.name:默认名称}") // 冒号后是默认值，防止配置不存在报错 private String demoName; @Value("${demo.desc:默认描述}") private String demoDesc; @Value("${server.port:8080}") private String serverPort; /** * 接口：获取配置信息 */ @GetMapping("/getConfig") public String getConfig() { return String.format( "当前环境端口：%s <br/> demo.name：%s <br/> demo.desc：%s", serverPort, demoName, demoDesc ); } } 

4.2 方式 2：NacosContextRefresher（手动刷新，进阶）

若需要手动触发配置刷新（如接口触发），可注入NacosContextRefresher：

java

运行

package com.example.controller; import com.alibaba.boot.nacos.config.context.event.NacosContextRefresher; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; @RestController public class RefreshController { @Autowired private NacosContextRefresher nacosContextRefresher; /** * 手动触发配置刷新接口 */ @GetMapping("/refreshConfig") public String refreshConfig() { nacosContextRefresher.refresh(); // 手动刷新配置 return "配置刷新成功！"; } } 

4.3 启动类编写

创建NacosConfigDemoApplication，无特殊配置，仅需@SpringBootApplication：

java

运行

package com.example; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; @SpringBootApplication public class NacosConfigDemoApplication { public static void main(String[] args) { SpringApplication.run(NacosConfigDemoApplication.class, args); } } 

步骤 5：测试验证（核心！验证效果）

5.1 验证动态配置刷新

1. 启动 Spring Boot 项目，访问接口：http://127.0.0.1:8081/getConfig；
   • 输出：当前环境端口：8081 <br/> demo.name：开发环境-测试名称 <br/> demo.desc：这是开发环境的动态配置；
2. 打开 Nacos 控制台→dev命名空间→编辑nacos-config-demo.yml：
   • 修改demo.name为开发环境-修改后的名称，demo.desc为开发环境动态刷新测试；
   • 点击「发布」；
3. 无需重启项目，再次访问http://127.0.0.1:8081/getConfig；
   • 输出：当前环境端口：8081 <br/> demo.name：开发环境-修改后的名称 <br/> demo.desc：开发环境动态刷新测试；
   • ✅ 验证成功：配置已动态刷新，无需重启服务！

5.2 验证多环境配置切换

1. 停止项目，修改application.yml中的nacos.config.namespace为test-456（测试环境命名空间 ID）；
2. 重启项目，访问http://127.0.0.1:8082/getConfig；
   • 输出：当前环境端口：8082 <br/> demo.name：测试环境-测试名称 <br/> demo.desc：这是测试环境的动态配置；
3. 同理，切换为prod-789（生产环境），重启后访问http://127.0.0.1:8083/getConfig，会显示生产环境配置；
   • ✅ 验证成功：多环境配置隔离生效！

进阶：多环境配置最佳实践（生产级）

上述方式通过修改namespace切换环境，适合开发阶段；生产环境推荐「启动参数指定环境」，无需修改配置文件：

1. 启动时指定环境（推荐）

打包项目为 JAR 包后，通过启动参数指定命名空间（环境）：

bash

运行

# 开发环境 java -jar nacos-config-demo-1.0.0.jar --nacos.config.namespace=dev-123 # 测试环境 java -jar nacos-config-demo-1.0.0.jar --nacos.config.namespace=test-456 # 生产环境 java -jar nacos-config-demo-1.0.0.jar --nacos.config.namespace=prod-789 

2. 配置分层（多服务共享配置）

生产环境中，多个服务可能共享部分配置（如数据库连接），可通过shared-configs配置共享配置集：

yaml

nacos: config: server-addr: 127.0.0.1:8848 namespace: dev-123 group: DEFAULT_GROUP data-id: nacos-config-demo.yml type: YAML refresh-enabled: true # 配置共享配置集（多个服务共用） shared-configs: - data-id: common-db.yml # 数据库共享配置 group: DEFAULT_GROUP refresh: true # 共享配置也支持动态刷新 - data-id: common-redis.yml # Redis共享配置 group: DEFAULT_GROUP refresh: true 

常见问题 & 避坑指南

1. 配置不刷新：
   • 检查nacos.config.refresh-enabled=true是否开启；
   • 检查是否添加@RefreshScope注解（仅作用于 Bean，需加在 Controller/Service 上）；
   • 检查 Nacos 配置的Data ID/Group/Namespace是否和项目配置一致。
2. 版本冲突：
   • 严格按照「前置准备」中的版本匹配表选择依赖版本；
   • 排除nacos-config-spring-boot-starter内置的低版本nacos-client。
3. 配置读取不到：
   • 检查 Nacos 服务端地址是否正确（集群需用逗号分隔）；
   • 检查命名空间 ID 是否填错（不是名称，是自动生成的 ID）；
   • @Value注解添加默认值（如${demo.name:默认值}），避免配置不存在导致启动失败。

总结

1. Spring Boot 整合 Nacos 配置中心的核心是引入nacos-config-spring-boot-starter，配置 Nacos 连接信息（地址、命名空间、Data ID）；
2. 动态配置刷新的关键是开启refresh-enabled=true，并在需要刷新的 Bean 上添加@RefreshScope注解；
3. 多环境配置通过「命名空间（Namespace）」隔离，生产环境推荐用启动参数指定命名空间，避免修改配置文件；
4. 生产环境可通过shared-configs实现配置分层，提升配置管理效率。