官方下载：https://nacos.io/download/nacos-server/
适用版本：Nacos 2.x / 3.x
环境：Windows / Linux / 本地部署
关键词：Nacos、MySQL、JDK、启动失败、配置中心

---

写在前面

在本地部署 Nacos 时，常见问题往往不是技术难点，而是：

配置写错
环境变量缺失
数据库细节问题
启动模式错误

这些问题叠加后，最终表现为：

启动失败 / 闪退 / 无法访问控制台

本文目标：让你 10 分钟内定位并解决问题

---

目录

1. 数据库连接篇

   • 坑1：密码里的 # 被注释截断
   • 坑2：MySQL 8+ Public Key Retrieval 限制
   • 坑3：配置参数名错误（.0 后缀缺失）
   • 坑4：MySQL 驱动版本不兼容
   • 坑5：数据库初始化脚本未执行

2. 环境与启动篇

   • 坑6：集群模式跑单机 → 反复重试闪退
   • 坑7：JDK 版本不匹配（2.x/3.x 要求不同）
   • 坑8：JVM 内存配置导致 OOM 或启动缓慢
   • 坑9：端口冲突（8848、9848、9849 等）
   • 坑10：启动窗口一闪而过，日志不知从何看起
   • 坑11：Derby 数据残留干扰 MySQL 模式

3. 控制台与鉴权篇

   • 坑12：控制台白屏 / 404
   • 坑13：多环境配置混淆（Namespace 未隔离）

4. 自检清单

---

数据库连接篇

坑1：密码中的 # 被当作注释符

现象：
启动日志出现 db-load-error、load jdbc.properties error，最终 db.num is null。

原配置（conf/application.properties）：

db.url.0=jdbc:mysql://127.0.0.1:3306/nacos?...&useSSL=false&serverTimezone=UTC
db.user.0=root
db.password.0=556JKAD@#79632bbc   #   # 后面的字符全部被忽略

原因：
.properties 文件中 # 表示注释开头，密码中的 # 导致实际密码只剩 556JKAD@，数据库连接认证失败。

解决方案：

方式	示例
转义 #	db.password.0=556JKAD\@\#79632bbc
URL 编码	db.password.0=556JKAD%40%2379632bbc
修改数据库密码（推荐）	去掉 # 等特殊字符，如 Root123456

---

坑2：MySQL 8+ 的 Public Key Retrieval is not allowed

现象：

Caused by: com.mysql.cj.exceptions.CJException: Public Key Retrieval is not allowed
Caused by: com.mysql.cj.exceptions.UnableToConnectException: Public Key Retrieval is not allowed

原因：
MySQL 8.0 默认使用 caching_sha2_password 认证插件，而 MySQL Connector/J 8.0+ 出于安全考虑，在 useSSL=false 时默认禁止客户端自动从服务器获取公钥。

解决方案：

1. 在 JDBC URL 中添加参数（推荐）：

   db.url.0=jdbc:mysql://127.0.0.1:3306/nacos?characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true&useUnicode=true&useSSL=false&serverTimezone=UTC&allowPublicKeyRetrieval=true
   

2. 修改 MySQL 用户的认证插件：

   ALTER USER 'root'@'%' IDENTIFIED WITH mysql_native_password BY '你的密码';
   FLUSH PRIVILEGES;
   

---

坑3：配置参数名错误（Nacos 3.x 的隐藏要求）

错误写法：

db.user=root
db.password=123456

正确写法（支持多数据源）：

db.user.0=root
db.password.0=123456

原因：
Nacos 3.x 允许配置多个数据库（db.num 可以大于 1），因此每个数据源必须有下标后缀 .0、.1 等。

---

坑4：MySQL 驱动版本不兼容

现象：
启动时出现 java.sql.SQLException: No suitable driver found 或各种奇怪的连接超时。

原因：
使用过旧的 MySQL Connector/J（如 5.1.x）连接 MySQL 8+，驱动不识别新认证方式或新协议。

解决方案：

• 下载 MySQL Connector/J 8.0.x 的 jar 包（如 mysql-connector-java-8.0.33.jar）
• 将其放入 ${NACOS_HOME}/plugins/mysql/ 目录（若目录不存在则手动创建）
• 重启 Nacos

---

坑5：数据库初始化脚本未执行

现象：
连接成功，但启动后部分功能异常，日志中出现 Table 'nacos.config_info' doesn't exist。

原因：
只配置了连接信息，但忘记执行 Nacos 提供的建表脚本。

解决方案：

1. 找到脚本文件（位置可能不同）：

   • 旧版：${NACOS_HOME}/conf/nacos-mysql.sql
   • 新版：${NACOS_HOME}/conf/mysql-schema.sql

2. 在 MySQL 中执行：

   CREATE DATABASE nacos DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
   USE nacos;
   SOURCE D:/nacos/conf/mysql-schema.sql;   -- Windows 路径
   

3. 验证表是否生成：

   SHOW TABLES;  -- 应看到 config_info, his_config_info, users 等表
   

---

🔧 环境与启动篇

坑6：集群模式跑单机 → 反复重试并闪退

现象：
启动后 log 显示 Nacos is starting... 循环很多次，最后 ERROR 退出。
日志中可能有 The server IP list of Nacos is []。

原因：
Nacos 默认以集群模式启动（MODE="cluster"），但单机环境下没有配置集群节点，会自动重试直至失败。

解决方案：

• 临时指定单机模式：

  startup.cmd -m standalone
  

• 永久修改（编辑 bin/startup.cmd 或 startup.sh）：

  set MODE="standalone"   # Windows
  export MODE="standalone" # Linux
  

---

坑7：JDK 版本不匹配

现象：
启动时直接报 Unsupported major.minor version 或 Java 命令行错误。

要求：

• Nacos 2.x：需要 JDK 8+（推荐 8u202+）
• Nacos 3.x：需要 JDK 11+（推荐 11 或 17 LTS）

解决方案：
安装对应版本 JDK，并正确设置 JAVA_HOME 和 PATH。

---

坑8：JVM 内存配置不当

现象：
启动缓慢，或出现 java.lang.OutOfMemoryError: Java heap space。

默认 JVM 参数（startup.cmd / startup.sh 中）：

-Xms2g -Xmx2g -Xmn1g   # 占用 2G 堆内存

解决方案：
修改 JVM 参数以适应自己的机器（例如 512MB）：

# Windows startup.cmd
set "JAVA_OPT=%JAVA_OPT% -server -Xms512m -Xmx512m -Xmn256m"
# Linux startup.sh
JAVA_OPT="${JAVA_OPT} -server -Xms512m -Xmx512m -Xmn256m"

注意：如果使用 Docker 部署，可通过环境变量 JVM_XMS、JVM_XMX 覆盖。

---

坑9：端口冲突（8848、9848、9849…）

现象：
启动时报 Address already in use: bind，或者无法访问控制台。

Nacos 2.x+ 端口占用规则：

端口	用途
8848	主端口（HTTP / 控制台）
9848	gRPC 通信端口（主端口 + 1000）
9849	gRPC 请求端口（主端口 + 1001）

解决方案：

1. 检查端口占用：

   netstat -ano | findstr :8848
   netstat -ano | findstr :9848
   

2. 修改主端口（application.properties）：

   server.port=8888
   

   注意：偏移端口会自动调整（9888、9889），需确保新端口范围未被占用。

3. 杀死占用进程（Windows）：

   taskkill /F /PID <占用进程的PID>
   

---

坑10：启动窗口一闪而过，日志不知从何看起

现象：
双击 startup.cmd，黑框一闪就消失，完全看不到错误信息。

解决方案：

1. 手动在命令行中执行：

   cd D:\nacos\bin
   set MODE=standalone
   java -jar ..\target\nacos-server.jar
   

   此时所有错误会直接打印在控制台。

2. 查看日志文件：

   • ${NACOS_HOME}/logs/nacos.log —— 最核心的日志
   • ${NACOS_HOME}/logs/start.out —— 启动输出

3. 修改启动脚本，暂停以便观察：
   在 startup.cmd 最后加一行 pause。

---

坑11：Derby 数据残留干扰 MySQL 模式

现象：
明明配置了 MySQL，但启动时却看到 Derby 相关的日志，或者配置信息还是旧数据。

原因：
Nacos 默认使用嵌入式 Derby 数据库，即使你配置了 spring.sql.init.platform=mysql，旧的 Derby 文件（${NACOS_HOME}/data）仍会被读取或干扰。

解决方案：

• 切换到 MySQL 前，删除 Derby 数据目录：

  rd /s /q D:\nacos\data
  

• 或者重命名 data 目录作为备份。

注意：删除 data 会丢失所有配置/服务数据，仅适用于全新部署。

---

控制台与鉴权篇

坑12：控制台白屏 / 404

现象：
访问 http://localhost:8848/nacos 一片空白或 404。

原因与解决方案：

原因	解决方案
路径不对	默认访问路径是 /nacos，尝试 http://localhost:8848 看是否有重定向。
server.servlet.context-path 被改过	检查 application.properties 中是否正确设置为 /nacos。
鉴权未开启导致页面不加载（2.2.2+）	开启鉴权：nacos.core.auth.enabled=true。
静态资源未加载	清除浏览器缓存，或尝试无痕模式。

开启鉴权后的登录信息：

• 默认用户名：nacos
• 默认密码：nacos
• 配置文件中可修改默认 token 等。

---

坑13：多环境配置混淆（Namespace 未隔离）

现象：
本地修改配置后，生产环境也变了；或者反过来。

原因：
不同环境共用同一个 Namespace（默认 public），导致配置互相影响。

解决方案：

1. 在 Nacos 控制台创建不同的 Namespace（如 dev、prod）。
2. 注意 Namespace 的 ID 才是客户端需要配置的值，而不是名称。
3. 客户端指定 Namespace：

   spring.cloud.nacos.config.namespace=dev-id-xxx
   

---

自检清单

检查项	状态
启动模式是 standalone（单机）还是 cluster（集群）	☐
JDK 版本 ≥ 8（2.x）/ ≥ 11（3.x）	☐
JAVA_HOME 环境变量正确	☐
JVM 堆内存大小适配本地内存（修改 startup.cmd/sh）	☐
端口 8848、9848、9849 未被占用	☐
MySQL 驱动 jar 包已在 plugins/mysql/ 目录下	☐
数据库已创建并执行了初始化脚本	☐
db.num 配置正确，且 db.url.0 等带 .0 后缀	☐
密码中若含 #、@ 等特殊字符，已转义或编码	☐
MySQL 8+ 已添加 allowPublicKeyRetrieval=true	☐
从 Derby 切换 MySQL 时已删除 data 目录	☐
控制台访问路径正确、鉴权已开启（如需要）	☐
不同环境使用不同 Namespace，并在客户端指定 ID	☐

---

附：快速修复一份可工作的 application.properties（MySQL 版）

# 数据源
spring.sql.init.platform=mysql
db.num=1

# 连接 URL（注意 allowPublicKeyRetrieval=true 和 时区）
db.url.0=jdbc:mysql://127.0.0.1:3306/nacos?characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true&useUnicode=true&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true

db.user.0=root
# 如果密码包含特殊字符，用 \ 转义或 URL 编码，最好是不使用特殊字符的密码
db.password.0=YourSimplePassword

# 其他核心配置
nacos.core.auth.enabled=true      # 开启鉴权（若需要）
server.port=8848

---

结语

Nacos 启动失败往往不是代码问题，而是环境配置、版本差异、符号转义等“小细节”的叠加。
希望这份踩坑笔记能帮你节约数小时的排查时间。

---

⭐ 如果这篇文章帮到了你，欢迎点赞 + 收藏 + 评论 ⭐