Nacos 入门教程：本地启动、配置中心与服务发现（Spring Boot 实战）

新手一屏速览

本地用 Docker 启动 Nacos（standalone）→ 浏览器访问控制台
Spring Boot 集成配置中心与发现；配置项热更新，属性留默认回退便于本地运行
提供完整可复制文件：docker-compose.yml、pom.xml、Java 源码、测试代码

1. Docker 启动 Nacos（可直接复制）

保存为 docker-compose.yml：

version: "3.8"
services:
  nacos:
    image: nacos/nacos-server:v2.2.3
    container_name: nacos
    environment:
      - MODE=standalone
      - PREFER_HOST_MODE=hostname
    ports:
      - "8848:8848"
      - "9848:9848"

启动：

docker compose up -d

访问控制台：浏览器打开 http://localhost:8848/nacos （默认用户名/密码：nacos/nacos）。

2. Spring Boot 集成（配置中心 + 发现）

pom.xml（可直接复制）：

<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>
  <groupId>com.example</groupId>
  <artifactId>nacos-demo</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <packaging>jar</packaging>
  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.2.5</version>
  </parent>
  <properties>
    <java.version>21</java.version>
    <spring-cloud.version>2023.0.1</spring-cloud.version>
    <spring-cloud-alibaba.version>2023.0.1.0</spring-cloud-alibaba.version>
  </properties>
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-dependencies</artifactId>
        <version>${spring-cloud.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
      <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>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <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>
    <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>
      </plugin>
    </plugins>
  </build>
</project>

application.yml（推荐写法，使用 config import）：

server:
  port: 8081
spring:
  application:
    name: nacos-demo
  cloud:
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848
      config:
        server-addr: 127.0.0.1:8848
        file-extension: properties
# 从 Nacos 导入远程配置（dataId=example.properties, group=DEFAULT_GROUP）
spring:
  config:
    import: optional:nacos:example.properties

DemoApplication.java：

package com.example.nacosdemo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * 应用启动入口。
 */
@SpringBootApplication
public class DemoApplication {
  /**
   * 启动应用
   * @param args 命令行参数
   */
  public static void main(String[] args) {
    SpringApplication.run(DemoApplication.class, args);
  }
}

ApiResponse.java：

package com.example.nacosdemo.web;

/**
 * 统一响应对象。
 * @param <T> 数据类型
 */
public class ApiResponse<T> {
  private boolean success;
  private T data;
  private String error;
  public static <T> ApiResponse<T> ok(T data){ ApiResponse<T> r=new ApiResponse<>(); r.success=true; r.data=data; return r; }
  public static <T> ApiResponse<T> fail(String msg){ ApiResponse<T> r=new ApiResponse<>(); r.success=false; r.error=msg; return r; }
  public boolean isSuccess(){ return success; } public T getData(){ return data; } public String getError(){ return error; }
}

HelloController.java（读取远程配置 app.message，带默认值回退，便于未启动 Nacos 时本地运行）：

package com.example.nacosdemo.web;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * 示例接口：返回来自配置中心的消息。
 */
@RestController
public class HelloController {
  @Value("${app.message:default-from-local}")
  private String message;

  /**
   * GET /api/message
   * @return 统一响应
   */
  @GetMapping("/api/message")
  public ApiResponse<String> message(){
    return ApiResponse.ok(message);
  }
}

3. 在 Nacos 控制台创建配置

在 DataID 填写 example.properties，Group 默认 DEFAULT_GROUP，内容：

app.message=hello-from-nacos

发布后访问：

curl http://localhost:8081/api/message

应返回 hello-from-nacos，未连接时返回本地默认 default-from-local。

4. 单元测试（可直接复制）

最近建一些几十个工作内推群，各大城市都有，群里目前已经收集了很多内推岗位，大厂、中厂、小厂、外包都有。欢迎HR、开发、测试、运维和产品加入。

内推群海报

扫描下方微信，备注：网站+所在城市，即可拉你进工作内推群。

微信二维码

package com.example.nacosdemo;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.web.servlet.MockMvc;

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;

/**
 * 验证本地默认值生效（无需依赖 Nacos 运行）。
 */
@SpringBootTest
@AutoConfigureMockMvc
class MessageControllerTest {
  @Autowired
  MockMvc mvc;
  @Test
  void should_return_default_when_nacos_unavailable() throws Exception {
    mvc.perform(get("/api/message"))
        .andExpect(status().isOk())
        .andExpect(jsonPath("$.success").value(true))
        .andExpect(jsonPath("$.data").value("default-from-local"));
  }
}

5. 启动项目与访问

mvn -q -DskipTests spring-boot:run

访问：

curl http://localhost:8081/api/message

6. 常见问题排查

无法连接 Nacos：确认端口 8848 开放、server-addr 正确、容器已启动
导入配置失败：确认 spring.config.import 语法，或改用 bootstrap.yml 传统方式
服务发现未生效：在需要的服务上引入 nacos-discovery 并在控制台查看实例列表