Nacos框架整合 02，Spring Boot 集成 Nacos 配置中心实现配置热更新-开发者社区

在微服务架构中，配置管理是核心环节之一。传统的配置文件方式存在修改后需重启服务、配置分散难以统一管理等问题。Alibaba Nacos 作为一款轻量级的配置中心和服务发现组件，能完美解决这些痛点，尤其是配置热更新能力，可在不重启服务的前提下实时生效配置变更。本文将详细讲解如何在 Spring Boot 项目中集成 Nacos 配置中心，并实现配置热更新。

一、环境准备

1. 前置条件

JDK 8 及以上版本
Maven 3.6+
Nacos Server（推荐 2.x 版本），下载地址：Nacos 官方下载
Spring Boot 2.x（本文以 2.7.10 为例）

2. 启动 Nacos Server

下载 Nacos 后，解压并进入bin目录，执行启动命令：

# Linux/Mac 系统 sh startup.sh -m standalone # Windows 系统 startup.cmd -m standalone

启动成功后，访问http://localhost:8848/nacos，默认账号密码均为nacos，即可进入 Nacos 控制台。

二、创建 Spring Boot 项目并引入依赖

1. 初始化项目

可通过 Spring Initializr（https://start.spring.io/）快速创建 Spring Boot 项目，或手动在 pom.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 https://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.10</version> <relativePath/> <!-- lookup parent from repository --> </parent> <groupId>com.example</groupId> <artifactId>nacos-config-demo</artifactId> <version>0.0.1-SNAPSHOT</version> <name>nacos-config-demo</name> <description>Demo project for Spring Boot + Nacos Config</description> <properties> <java.version>1.8</java.version> <!-- 统一管理 Nacos 版本 --> <nacos-config-spring-boot.version>0.2.12</nacos-config-spring-boot.version> </properties> <dependencies> <!-- Spring Boot Web 依赖，用于测试接口 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- Nacos Config Spring Boot 核心依赖 --> <dependency> <groupId>com.alibaba.boot</groupId> <artifactId>nacos-config-spring-boot-starter</artifactId> <version>${nacos-config-spring-boot.version}</version> </dependency> <!-- lombok 简化代码（可选） --> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <optional>true</optional> </dependency> <!-- Spring Boot 测试依赖（可选） --> <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>

三、配置 Nacos 连接信息

在 Spring Boot 项目的application.yml（或application.properties）中配置 Nacos 服务地址及配置中心基础信息：

server: port: 8080 # 项目启动端口 # Nacos 配置中心配置 nacos: config: server-addr: localhost:8848 # Nacos Server 地址 namespace: public # 命名空间（默认public，可自定义） group: DEFAULT_GROUP # 配置分组（默认DEFAULT_GROUP） type: YAML # 配置文件类型（支持 YAML/Properties/JSON 等） refresh-enabled: true # 开启配置自动刷新（核心，默认true，显式配置更清晰）

四、实现配置热更新的两种方式

Nacos 支持两种主流的配置热更新方式，分别适用于不同场景，下面逐一讲解。

方式一：使用 @NacosValue 注解（原生 Nacos 注解）

这是 Nacos 提供的原生注解，可直接绑定配置项并支持热更新，步骤如下：

1. 启动类添加 @NacosPropertySource 注解

在 Spring Boot 启动类上添加注解，指定 Nacos 中的配置数据 ID（即配置文件名），并开启自动刷新：

import com.alibaba.nacos.spring.context.annotation.config.NacosPropertySource; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; /** * 启动类：绑定 Nacos 配置源，开启自动刷新 * dataId：nacos-config-demo.yml（对应 Nacos 控制台中创建的配置文件名） * autoRefreshed：true 开启配置热更新 */ @SpringBootApplication @NacosPropertySource(dataId = "nacos-config-demo.yml", autoRefreshed = true) public class NacosConfigDemoApplication { public static void main(String[] args) { SpringApplication.run(NacosConfigDemoApplication.class, args); } }

2. 创建测试 Controller，绑定配置项

编写 Controller，通过@NacosValue注解绑定 Nacos 中的配置值，并提供接口测试配置是否生效：

import com.alibaba.nacos.api.config.annotation.NacosValue; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; /** * 测试配置热更新的控制器 */ @RestController public class ConfigController { /** * 绑定 Nacos 中的配置项：app.name * defaultValue：默认值（当 Nacos 中无该配置时使用） */ @NacosValue(value = "${app.name:默认应用名称}", autoRefreshed = true) private String appName; /** * 绑定 Nacos 中的配置项：app.version */ @NacosValue(value = "${app.version:1.0.0}", autoRefreshed = true) private String appVersion; /** * 暴露接口，获取当前配置值 */ @GetMapping("/getConfig") public String getConfig() { return "应用名称：" + appName + "，版本号：" + appVersion; } }

方式二：使用 @ConfigurationProperties 注解（Spring 原生方式）

对于配置项较多的场景，推荐使用 Spring 原生的@ConfigurationProperties注解，将配置绑定到实体类，更符合 Spring 开发习惯。

1. 创建配置实体类

import lombok.Data; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.stereotype.Component; /** * 配置实体类：绑定以 app 为前缀的配置项 */ @Data @Component @ConfigurationProperties(prefix = "app") public class AppConfigProperties { // 对应 Nacos 中的 app.name private String name = "默认应用名称"; // 对应 Nacos 中的 app.version private String version = "1.0.0"; // 可扩展更多配置项 private String env = "dev"; }

2. 创建测试 Controller，注入配置实体类

import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; import javax.annotation.Resource; /** * 测试 ConfigurationProperties 方式的配置热更新 */ @RestController public class ConfigPropertiesController { @Resource private AppConfigProperties appConfigProperties; @GetMapping("/getPropertiesConfig") public String getPropertiesConfig() { return "应用名称：" + appConfigProperties.getName() + "，版本号：" + appConfigProperties.getVersion() + "，环境：" + appConfigProperties.getEnv(); } }

注意：使用@ConfigurationProperties时，需确保nacos.config.refresh-enabled=true（默认开启），否则无法触发热更新。

五、Nacos 控制台创建配置

登录 Nacos 控制台（http://localhost:8848/nacos）；
进入「配置管理」→「配置列表」，点击「+ 新增配置」；
填写配置信息：
- Data ID：nacos-config-demo.yml（需与启动类@NacosPropertySource中的 dataId 一致）；
- 分组：DEFAULT_GROUP（与 application.yml 中配置的 group 一致）；
- 配置格式：YAML；
- 配置内容：
```
app: name: Nacos配置中心测试应用 version: 2.0.0 env: prod
```
点击「发布」，完成配置创建。

六、测试配置热更新

1. 启动 Spring Boot 项目

运行启动类NacosConfigDemoApplication，项目启动后访问以下接口：

方式一测试接口：http://localhost:8080/getConfig输出：应用名称：Nacos配置中心测试应用，版本号：2.0.0
方式二测试接口：http://localhost:8080/getPropertiesConfig输出：应用名称：Nacos配置中心测试应用，版本号：2.0.0，环境：prod

2. 修改 Nacos 配置并测试热更新

在 Nacos 控制台修改配置内容，例如：

app: name: Nacos配置热更新测试 version: 3.0.0 env: test

点击「发布」后，无需重启 Spring Boot 项目，再次访问上述接口：

方式一接口输出：应用名称：Nacos配置热更新测试，版本号：3.0.0
方式二接口输出：应用名称：Nacos配置热更新测试，版本号：3.0.0，环境：test

可见配置已实时生效，实现了热更新。

七、关键注意事项

Data ID 命名规范：建议遵循{应用名}.{格式}（如 nacos-config-demo.yml），便于区分不同应用的配置；
命名空间（Namespace）：可用于隔离不同环境（dev/test/prod）的配置，需在 application.yml 中指定对应 namespace 的 ID（非名称）；
配置刷新时机：Nacos 客户端默认每 3000ms 拉取一次配置（可通过nacos.config.refresh-delay调整），修改配置后可能有短暂延迟；
注解使用规范：
- @NacosValue需显式指定autoRefreshed = true才会热更新；
- @ConfigurationProperties无需额外配置，依赖全局的refresh-enabled = true；
配置优先级：Nacos 配置中心的配置优先级高于本地 application.yml，会覆盖本地同名配置。