Nacos服务注册从零上手：配置、步骤与避坑指南

知识分享

2026-06-17 01:40

9 阅读

为什么要把服务注册到 Nacos

在微服务架构中，服务之间需要知道彼此的网络地址才能通信。
Nacos 作为注册中心，可以帮每个服务在启动时自动“上报”自己的 IP 和端口，其他服务通过 Nacos 就能找到它。
这个动作就叫 Nacos 服务注册。
本文会带你从零开始，把一个小服务注册到 Nacos，并验证是否成功。

首先需要有一个运行中的 Nacos 服务端。
如果你是第一次接触，建议直接使用最新的稳定版。

打开浏览器访问 http://127.0.0.1:8848/nacos，默认用户名密码都是 nacos，登录后看到控制台界面表示 Nacos 启动成功。

提示：生产环境建议使用 MySQL 作为后端存储并配置集群，但新手测试单机模式就够用。

假设你已有一个 Spring Boot 项目（版本 2.x 或 3.x），现在要把它注册到上面启动的 Nacos。

第一步：添加依赖

在 pom.xml 中加入：


    com.alibaba.cloud
    spring-cloud-starter-alibaba-nacos-discovery
    2021.0.5.0

版本号以你使用的 Spring Cloud Alibaba 版本为准，也可以不写版本，通过 BOM 管理。

第二步：配置 Nacos 地址

在 application.yml 或 bootstrap.yml 中写入：

spring:
  application:
    name: my-service   # 注册到 Nacos 的服务名
  cloud:
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848

如果你使用了 namespace 或 group，可以补充：

        namespace: your-namespace-id
        group: your-group-name

第三步：启动应用

在启动类上加上 @EnableDiscoveryClient（Spring Cloud 旧版本需要，新版本自动启用，可省略）。
直接运行 main 方法。

启动日志中如果看到类似“Registering service ... to nacos”的字样，说明注册请求已发送。

如果你用命令行验证，可以执行：

curl -X GET 'http://127.0.0.1:8848/nacos/v1/ns/instance/list?serviceName=my-service'

返回 JSON 中包含 hosts 数组，说明实例已注册。

网络不通：Nacos 地址写成了 localhost 但容器或远程部署时需用实际 IP，或者防火墙未放行 8848 端口。
命名空间不匹配：服务端创建了命名空间，客户端配置的 namespace 必须和服务端一致（否则服务会注册到 public 空间）。
服务名冲突：不同服务使用相同 spring.application.name，会被 Nacos 认为是同一服务的不同实例。
依赖版本冲突：spring-cloud-starter-alibaba-nacos-discovery 的版本需与 Spring Boot 及 Spring Cloud 版本对应，否则可能启动报错 NoClassDefFoundError。

Q：服务注册后几分钟在控制台看不到？
A：检查客户端日志是否有连接 Nacos 失败的信息，常见原因是 server-addr 写错或 Nacos 未启动。同时确认客户端网络能访问 8848 端口。

Q：如何临时下线一个服务实例？
A：在 Nacos 控制台的服务详情页，点击实例后的“下线”按钮，或调用 API 设置 healthy=false。

Nacos 服务注册本身并不复杂，核心就是三步：启动 Nacos Server、配置客户端、启动应用。
初次上手时多留意网络、命名空间和版本兼容这几个点。
如果你正在处理相关任务，建议先按本文步骤完整执行一遍，再根据自己的环境微调。
遇到异常时优先回看避坑和高频问题部分。