Nacos 入门学习文档

基于 Nacos 1.4.4 + Spring Boot 2.6.x + Spring Cloud Alibaba 2.2.9.RELEASE

---

一、Nacos 是什么

Nacos = 服务注册中心 + 配置中心，是阿里巴巴开源的中间件。

功能	说明
服务注册与发现	微服务启动后自动注册，其他服务可以通过服务名调用
配置管理	集中管理配置文件，支持热更新（不重启服务生效）

---

二、下载与安装

2.1 下载

前往 GitHub Release 页面下载对应版本：

https://github.com/alibaba/nacos/releases/tag/1.4.4

下载 nacos-server-1.4.4.zip，解压到本地目录，例如：

D:\nacos\

解压后目录结构：

nacos/
├── bin/         ← 启动脚本
├── conf/        ← 配置文件（application.properties、nacos-mysql.sql）
├── logs/
└── data/

---

三、初始化数据库（MySQL 模式）

Nacos 默认使用内嵌数据库，生产环境建议换成 MySQL。

3.1 创建数据库

CREATE DATABASE nacos_config DEFAULT CHARACTER SET utf8mb4;

3.2 执行初始化 SQL

SQL 文件在解压目录的 conf/nacos-mysql.sql，在 nacos_config 库中执行：

mysql -u root -p nacos_config < conf/nacos-mysql.sql

或者用 Navicat / DataGrip 直接打开 conf/nacos-mysql.sql 执行。

3.3 修改 Nacos 配置文件

编辑 conf/application.properties，找到数据库相关配置取消注释并填写：

# 使用 MySQL 存储
spring.datasource.platform=mysql
db.num=1
db.url.0=jdbc:mysql://127.0.0.1:3306/nacos_config?characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true&useUnicode=true&useSSL=false&serverTimezone=UTC
db.user.0=root
db.password.0=你的密码

---

四、启动 Nacos

Windows 启动（单机模式）

# 进入 bin 目录
cd D:\nacos\bin

# 单机模式启动（开发用这个）
startup.cmd -m standalone

Linux/Mac 启动

sh startup.sh -m standalone

验证启动成功

浏览器访问：

http://127.0.0.1:8848/nacos

默认账号密码：nacos / nacos

---

五、Maven 依赖

在你的 pom.xml 中添加（注意版本对应关系）：

<!-- Nacos 服务注册 -->
<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
    <version>2.2.9.RELEASE</version>
</dependency>

<!-- Nacos 配置中心 -->
<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
    <version>2.2.9.RELEASE</version>
</dependency>

<!-- nacos-client 指定版本，避免冲突 -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client</artifactId>
    <version>1.4.4</version>
</dependency>

<!-- ⚠️ bootstrap 支持（必须加，否则 bootstrap.properties 不生效） -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-bootstrap</artifactId>
    <version>3.0.3</version>
</dependency>

版本对应关系

Spring Boot	Spring Cloud Alibaba	Nacos Client
2.6.x	2.2.9.RELEASE	1.4.4
2.7.x	2021.0.5.0	2.x

---

六、注册服务到 Nacos

6.1 ⚠️ 重要：配置必须写在 bootstrap.properties

Nacos 配置中心的连接信息必须写在 bootstrap.properties（或 bootstrap.yml）里。

原因：bootstrap 在 Spring 容器启动之前加载，application 是容器启动之后加载。 如果写在 application.properties 里，Nacos 连接还没建立，配置就已经用不上了。

6.2 创建 bootstrap.properties

在 src/main/resources/ 下创建 bootstrap.properties：

# 应用名（同时作为 Nacos 服务注册的服务名）
spring.application.name=java-demo

# Nacos 服务注册地址
spring.cloud.nacos.discovery.server-addr=127.0.0.1:8848

# Nacos 配置中心地址
spring.cloud.nacos.config.server-addr=127.0.0.1:8848
# 配置文件名（对应 Nacos 控制台的 Data ID）
spring.cloud.nacos.config.name=java-demo
# 配置文件格式
spring.cloud.nacos.config.file-extension=yaml
# 开启配置
spring.cloud.nacos.config.enabled=true

6.3 application.properties（本地业务配置）

server.port=8090

spring.datasource.url=jdbc:mysql://localhost:3306/your_db
spring.datasource.username=root
spring.datasource.password=yourpassword
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

6.4 启动类加注解

@SpringBootApplication
@EnableDiscoveryClient  // 开启服务注册发现
public class JavaDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(JavaDemoApplication.class, args);
    }
}

6.5 验证注册成功

启动应用后，打开 Nacos 控制台：

服务管理 → 服务列表

能看到 java-demo 说明注册成功。

---

七、使用 Nacos 配置中心

7.1 在 Nacos 控制台创建配置

进入 配置管理 → 配置列表 → 新建配置：

字段	填写内容
Data ID	java-demo.yaml
Group	DEFAULT_GROUP
配置格式	YAML
配置内容	见下方

配置内容示例：

test:
  name: 我是来自Nacos的配置
  age: 20

⚠️ Data ID 命名规则：${spring.cloud.nacos.config.name}.${file-extension} 本例就是 java-demo.yaml

7.2 在代码中读取配置

@RestController
@RefreshScope  // 加这个注解，Nacos 修改配置后自动刷新，不需要重启
public class TestController {

    @Value("${test.name}")
    private String name;

    @Value("${test.age}")
    private Integer age;

    @GetMapping("/test")
    public Map<String, Object> test() {
        Map<String, Object> map = new HashMap<>();
        map.put("name", name);
        map.put("age", age);
        return map;
    }
}

7.3 验证热更新

1. 启动应用，访问 /test 接口，返回 Nacos 中的配置值
2. 在 Nacos 控制台修改 test.name 的值，点击发布
3. 再次访问 /test，值已经更新（不需要重启服务）

---

八、常见注意事项

❌ 常见错误1：bootstrap 配置没生效

Could not resolve placeholder 'test.name' in value "${test.name}"

原因：Nacos 配置写在了 application.properties 而不是 bootstrap.properties。

解决：把 Nacos 连接相关配置移到 bootstrap.properties。

---

❌ 常见错误2：忘记加 bootstrap 依赖

Spring Boot 2.4+ 默认不再加载 bootstrap 文件，需要手动加依赖：

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-bootstrap</artifactId>
    <version>3.0.3</version>
</dependency>

---

❌ 常见错误3：Data ID 对不上

Nacos 控制台的 Data ID 必须等于：

${spring.cloud.nacos.config.name}.${spring.cloud.nacos.config.file-extension}

例如配置了 name=java-demo，file-extension=yaml，则 Data ID 必须是 java-demo.yaml。

---

❌ 常见错误4：yaml 格式写错

Nacos 中的 yaml 配置不能用 properties 格式：

# ✅ 正确
test:
  name: 张三
  age: 18

# ❌ 错误（这是 properties 格式）
test.name=张三

---

❌ 常见错误5：@RefreshScope 没加

不加 @RefreshScope，Nacos 配置更新后需要重启服务才能生效。

---

九、完整目录结构参考

src/main/resources/
├── bootstrap.properties   ← Nacos 连接配置（必须在这里）
└── application.properties ← 本地业务配置（数据库、端口等）

---

十、版本速查表

组件	版本
Nacos Server	1.4.4
Spring Boot	2.6.13
spring-cloud-starter-alibaba-nacos-discovery	2.2.9.RELEASE
spring-cloud-starter-alibaba-nacos-config	2.2.9.RELEASE
nacos-client	1.4.4
spring-cloud-starter-bootstrap	3.0.3