1. 为什么本地跑 Nacos 3.0.2 比想象中更容易翻车很多人第一次在 Windows 10 上装 Nacos心态都是不就是解压、双击启动脚本吗结果打开startup.cmd之后窗口一闪而过或者卡在Nacos started successfully之前疯狂报错最后连控制台都进不去。我前后在三四台不同配置的 Windows 10 机器上装过 Nacos 3.0.2 单机版踩的坑几乎每次都不一样有的是 JDK 版本不对有的是 MySQL 8.0 的驱动和连接串没配对还有的是 Windows 自带的命令行编码把日志搞成了乱码让人误以为是启动失败。这篇内容就是把这些真实踩过的坑摊开讲清楚。核心围绕Windows 10 Nacos 3.0.2 单机版 JDK 17 MySQL 8.0这套组合从环境准备、JDK 17 的安装与切换、MySQL 8.0 的建库建表到 Nacos 的配置修改、启动验证、常见报错排查一步步给你可复现的操作。适合刚接触微服务注册中心的后端开发、需要本地搭一套服务治理环境的测试同学以及被启动闪退折磨过的运维新手。需要先明确一点Nacos 3.x 相比 2.x 在鉴权、控制台路径、依赖组件上都有变化网上大量 2.x 的教程直接照搬会出问题。比如 3.0.2 默认开启了鉴权相关配置控制台地址也从/nacos变成了带端口和路径的新形式。所以这篇不会拿旧教程糊弄你所有步骤都按 3.0.2 的实际行为来写。另外提前说一个结论单机版模式下Nacos 默认用的是内嵌 Derby 数据库如果你不打算用 MySQL其实可以跳过数据库这一整块。但绝大多数人装 Nacos 是为了贴近生产环境而生产环境基本都用 MySQL 持久化所以这篇会把 MySQL 8.0 的接入完整讲一遍包括那个让无数人卡住的Public Key Retrieval is not allowed报错。2. 装 Nacos 之前先把 JDK 17 这件事彻底搞定2.1 为什么 Nacos 3.0.2 必须用 JDK 17 而不是 JDK 8Nacos 3.x 的编译和运行基线已经抬到了 JDK 17。如果你机器上还留着 JDK 8直接启动大概率会看到UnsupportedClassVersionError提示类文件版本是 61.0对应 JDK 17而你的 JVM 只认到 52.0对应 JDK 8。这个报错信息其实很直白但很多人看到一长串堆栈就慌了以为是 Nacos 本身有问题。我建议的做法是不要卸载原来的 JDK 8因为很多老项目、老工具还依赖它。正确姿势是让 JDK 17 和 JDK 8 共存通过环境变量切换。Windows 下切换 JDK 最干净的方式是改JAVA_HOME而不是去动Path里那一堆%JAVA_HOME%\bin。具体操作去 Oracle 官网或者国内镜像下载 JDK 17 的 Windows x64 安装包安装路径建议不要带空格和中文比如D:\dev\jdk-17。安装完之后打开系统属性 → 高级 → 环境变量新建一个JAVA_HOME值指向D:\dev\jdk-17。然后在Path里确保%JAVA_HOME%\bin排在旧 JDK 的路径前面。验证是否切换成功开一个新的 cmd 窗口注意必须是新开的旧窗口不会刷新环境变量执行java -version正常应该输出类似java version 17.0.x 2024-xx-xx LTS Java(TM) SE Runtime Environment (build 17.0.xxx-LTS-xxx) Java HotSpot(TM) 64-Bit Server VM (build 17.0.xxx-LTS-xxx, mixed mode, sharing)提示如果你执行java -version还是显示 1.8八成是 Path 里旧 JDK 的路径排在前面或者你开的 cmd 窗口是切换之前就打开的。关掉重开一次基本能解决。2.2 多 JDK 共存时怎么避免切了但没完全切这里有个很隐蔽的坑Windows 的Path里如果同时存在C:\Program Files\Common Files\Oracle\Java\javapath这种 Oracle 自动加的路径它会优先于你的JAVA_HOME。这个路径是安装 JDK 时自动写入的指向的是某个特定版本。解决办法是把这个javapath条目从Path里删掉或者把它挪到%JAVA_HOME%\bin后面。还有一个更省事的方案写两个批处理脚本一个叫use-jdk8.bat一个叫use-jdk17.bat内容就是临时设置当前窗口的JAVA_HOME和Path。这样你不需要反复改系统环境变量开哪个窗口用哪个版本。脚本大概长这样echo off set JAVA_HOMED:\dev\jdk-17 set PATH%JAVA_HOME%\bin;%PATH% echo JDK switched to 17 java -version这种临时切换的方式特别适合需要频繁在 JDK 8 和 JDK 17 之间来回切的场景改完只影响当前命令行窗口关掉就恢复不会污染系统配置。2.3 验证 JDK 17 是否真的被 Nacos 用上了光看java -version还不够因为 Nacos 启动脚本里可能会自己指定 JDK 路径。Nacos 3.0.2 的startup.cmd里有一段逻辑会检查JAVA_HOME如果没设置会尝试用默认的 java。所以启动之前最好在同一个 cmd 窗口里先echo %JAVA_HOME%确认一下再执行启动脚本。我遇到过一种情况系统环境变量改对了但 Nacos 启动脚本里被人手动写死了一个 JDK 8 的路径结果怎么切都没用。所以如果你拿到的是别人改过的 Nacos 包记得打开startup.cmd扫一眼有没有硬编码的set JAVA_HOME...。3. MySQL 8.0 的安装与 Nacos 专用库表初始化3.1 MySQL 8.0 安装时那几个容易选错的选项MySQL 8.0 在 Windows 上的安装推荐用官方的 MySQL Installer一路下一步虽然能装完但有几个选项选错了后面会很难受。第一个是认证方式。MySQL 8.0 默认用caching_sha2_password这个插件比老的mysql_native_password更安全但很多老客户端和驱动不认。Nacos 用的 JDBC 驱动如果是较新版本是支持caching_sha2_password的但需要连接串里加参数。我个人的建议是为了本地开发省事可以把 Nacos 连接用的那个用户改成mysql_native_password避免一堆认证相关的报错。改法后面会讲。第二个是端口。默认 3306如果你机器上已经有一个 MySQL 在跑安装时会提示端口冲突这时候要么改端口要么先停掉旧的。我一般会把 Nacos 专用的 MySQL 装在 3307 或者 3308跟日常用的那个隔离开省得互相干扰。第三个是字符集。MySQL 8.0 默认字符集已经是utf8mb4了这个没问题不用像 5.7 那样手动改my.ini。但如果你是从旧版本升级上来的记得检查一下character_set_server是不是utf8mb4。安装完成后用命令行登录验证mysql -u root -p -P 3306输入密码后能看到mysql提示符就说明装好了。3.2 建库、建用户、授权一步都别省Nacos 官方给的 SQL 脚本里只包含建表语句不含建库和建用户。所以你得先手动把库和用户准备好。我习惯用独立的库名和用户名方便管理CREATE DATABASE nacos_config DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; CREATE USER nacos% IDENTIFIED WITH mysql_native_password BY nacos123456; GRANT ALL PRIVILEGES ON nacos_config.* TO nacos%; FLUSH PRIVILEGES;这里有几个细节值得说。IDENTIFIED WITH mysql_native_password就是前面提到的把认证插件指定成老的避免驱动兼容问题。nacos%里的%表示允许从任意主机连接本地开发这样写没问题生产环境要收紧成具体 IP。密码别用太简单的虽然本地无所谓但养成习惯没坏处。注意MySQL 8.0 里GRANT语句不能再像 5.7 那样顺带创建用户了必须先CREATE USER再GRANT否则会报语法错误。这是 8.0 的一个明显变化。3.3 导入 Nacos 的建表脚本以及那个 767 字节的坑Nacos 3.0.2 的安装包里建表脚本在conf目录下文件名类似mysql-schema.sql。用命令行导入mysql -u nacos -p -P 3306 nacos_config D:\dev\nacos\conf\mysql-schema.sql导入过程中如果你看到类似ERROR 1071 (42000): Specified key was too long; max key length is 767 bytes的报错别慌这是 MySQL 索引长度限制导致的。在 MySQL 8.0 utf8mb4 下单个索引列最大长度是 3072 字节InnoDB 且开启了innodb_large_prefix一般不会触发 767 的限制。但如果你的表用的是utf8mb4且某些字段索引过长或者 MySQL 配置里innodb_large_prefix没开就可能撞上。解决办法有两个一是确认 MySQL 8.0 的innodb_default_row_format是DYNAMIC8.0 默认就是二是把报错的那张表的字符集临时改成utf8再导入。不过更稳妥的做法是直接用官方脚本官方脚本在 8.0 上是验证过的正常不会报 767。如果你是从网上抄的旧脚本那就要小心了。导入完成后验证一下表是否都在USE nacos_config; SHOW TABLES;应该能看到config_info、config_info_beta、his_config_info、users、roles等十几张表。表在数据库这块就算通了。4. Nacos 3.0.2 单机版的配置改造与启动4.1 解压之后先别急着启动改这几个地方Nacos 3.0.2 的压缩包解压出来目录结构大概是bin、conf、target这几块。启动脚本在bin下Windows 用startup.cmdLinux 用startup.sh。单机版启动默认是 Derby 模式。要切到 MySQL得改conf/application.properties。这个文件里默认有一堆被注释掉的配置你需要把 MySQL 相关的几行取消注释并改成自己的值spring.datasource.platformmysql db.num1 db.url.0jdbc:mysql://127.0.0.1:3306/nacos_config?characterEncodingutf8connectTimeout1000socketTimeout3000autoReconnecttrueuseUnicodetrueuseSSLfalseserverTimezoneAsia/ShanghaiallowPublicKeyRetrievaltrue db.user.0nacos db.password.0nacos123456这里每一个参数都有讲究。useSSLfalse是因为本地开发不需要 SSL开着反而可能因为证书问题连不上。serverTimezoneAsia/Shanghai是为了避免时区不一致导致的时间错乱MySQL 8.0 对时区比较敏感。allowPublicKeyRetrievaltrue是解决Public Key Retrieval is not allowed报错的关键这个报错在使用caching_sha2_password且没开 SSL 时特别常见。提示db.url.0这一行特别长改的时候注意别把后面的参数漏掉尤其是allowPublicKeyRetrievaltrue。我见过有人只改了库名和用户名密码结果卡在公钥检索报错上查了半天。4.2 单机模式怎么启动以及启动闪退的排查顺序Nacos 3.0.2 在 Windows 下启动单机版命令是startup.cmd -m standalone注意-m standalone这个参数不加的话默认是集群模式会去找cluster.conf找不到就报错退出。很多人双击startup.cmd直接闪退就是因为没带这个参数。如果你是在 cmd 里执行窗口一闪而过看不到报错可以先用cmd /k的方式运行或者直接看logs目录下的start.out和nacos.log。启动失败的线索基本都在这两个文件里。启动闪退的排查顺序我一般按这个来先确认java -version是 17不是 8。再确认startup.cmd里没有硬编码的旧 JDK 路径。然后看logs/start.out如果是数据库连接报错就往 MySQL 配置那块查。如果是端口占用看 8848 是不是被别的进程占了用netstat -ano | findstr 8848查。启动成功的标志是日志里出现Nacos started successfully in stand alone mode. use external storage看到use external storage就说明 MySQL 接入成功了如果显示的是use embedded storage那就是还在用 Derby说明你的 MySQL 配置没生效。4.3 控制台地址变了别再照着 2.x 的教程访问Nacos 3.0.2 的控制台地址跟 2.x 不一样。2.x 一般是http://localhost:8848/nacos3.0.2 改成了http://localhost:8848/nacos/index.html或者直接http://localhost:8848/具体取决于版本的小改动。最稳妥的方式是启动成功后看日志里打印的 console 地址日志里会明确写出来。第一次访问会要求登录Nacos 3.x 默认开启了鉴权默认用户名密码是nacos/nacos。登录进去之后建议第一时间改掉默认密码尤其是如果这台机器在局域网里能被别人访问到。如果访问控制台报 404先确认端口对不对再确认是不是被 Windows 防火墙拦了。本地开发可以把防火墙对 8848 端口放行或者临时关掉防火墙测试。5. 那些让我熬夜的报错以及它们的真实解法5.1 Public Key Retrieval is not allowed不是密码错是认证方式在作怪这个报错的全称是java.sql.SQLNonTransientConnectionException: Public Key Retrieval is not allowed。第一次遇到的人往往会以为是密码错了反复改密码其实跟密码一点关系都没有。根本原因是 MySQL 8.0 默认的caching_sha2_password插件在非 SSL 连接下需要客户端去服务器检索公钥来加密密码而 JDBC 驱动默认不允许这个行为。解决办法就是在连接串里加allowPublicKeyRetrievaltrue或者把用户的认证插件改成mysql_native_password。我一般两个都做双保险。如果你已经建好了用户但忘了改认证插件可以用这条语句改ALTER USER nacos% IDENTIFIED WITH mysql_native_password BY nacos123456; FLUSH PRIVILEGES;改完重启 Nacos 就行。5.2 时区报错The server time zone value is unrecognized这个报错在 MySQL 8.0 上也很常见原因是服务器时区没设置JDBC 驱动不知道该按哪个时区解析时间。解决方式就是在连接串里显式指定serverTimezoneAsia/Shanghai。如果加了还报错那可能是 MySQL 服务器本身的时区表没导入可以在 MySQL 里执行SET GLOBAL time_zone 8:00;或者在my.ini里加default-time-zone8:00然后重启 MySQL 服务。5.3 端口 8848 被占用先查再杀别乱重启8848 是 Nacos 的默认端口如果被别的程序占了Nacos 启动会失败。查占用的命令netstat -ano | findstr 8848最后一列是 PID拿到 PID 之后用任务管理器或者taskkill /PID xxx /F干掉。但要注意有些程序比如某些 IDE 的内置服务会占用这个端口杀之前先确认一下是什么进程别误杀了重要服务。如果实在不想改端口也可以改 Nacos 的端口在application.properties里加server.port8849但改完记得控制台地址也要跟着变。5.4 启动日志乱码Windows 命令行编码的锅Windows 中文版的 cmd 默认编码是 GBK而 Nacos 日志输出是 UTF-8两者不一致就会乱码。乱码本身不影响运行但会让你看不懂报错。解决办法是在启动之前执行chcp 65001把当前窗口切成 UTF-8或者用 PowerShell 启动。不过chcp 65001有时候会让中文显示成方块这时候可以试试用 Windows Terminal 或者 Git Bash 来跑。我个人的习惯是启动脚本里加一行chcp 65001 nul这样每次启动自动切编码省得手动敲。6. 启动成功之后怎么确认这套环境真的能用6.1 用控制台建一个配置验证 MySQL 持久化是否生效光看到启动成功还不够得实际写一条数据然后重启 Nacos看数据还在不在。如果重启后数据还在说明 MySQL 持久化真的生效了如果数据没了那说明还在用 Derby。操作很简单登录控制台进配置管理新建一个配置Data ID 随便写个test.yamlGroup 用默认的DEFAULT_GROUP内容写个key: value保存。然后重启 Nacos再回来看这条配置还在不在。这个验证步骤特别重要因为有些人配置改了但没生效自己不知道等到真正用的时候才发现数据存不住。6.2 服务注册的连通性测试别只信控制台配置能存只是第一步Nacos 的核心功能是服务注册与发现。可以写一个最简单的 Spring Boot 应用引入nacos-discovery依赖配置好注册中心地址启动后看服务列表里有没有出现。或者更轻量一点直接用 Nacos 的 Open API 发个注册请求curl -X POST http://localhost:8848/nacos/v1/ns/instance?serviceNametest-serviceip127.0.0.1port8080返回ok就说明注册接口通了。然后再查一下curl http://localhost:8848/nacos/v1/ns/instance/list?serviceNametest-service能看到实例信息就说明服务发现也正常。注意 3.x 的 API 路径可能跟 2.x 有差异如果 404 了去官方文档确认一下当前版本的 API 前缀。6.3 开机自启这件事单机版要不要做本地开发环境一般不需要开机自启每次手动启动反而更可控。但如果你把 Nacos 当成一个长期运行的服务可以考虑用 Windows 的任务计划程序或者nssm把它注册成系统服务。不过单机版 Nacos 本身不适合生产所以我的建议是本地开发就手动启动别折腾自启省得出问题不好排查。如果确实需要用nssm把startup.cmd包成服务是个可行方案但要注意工作目录和 JDK 环境变量的传递否则服务启动时会找不到 JDK 或者读不到配置文件。7. 我在多台机器上装完之后总结的几条经验第一JDK 17 和 JDK 8 共存时环境变量的顺序比版本本身更重要。很多人装好了 JDK 17但java -version还是 8就是 Path 顺序问题。养成改完环境变量就新开窗口验证的习惯。第二MySQL 8.0 的连接串参数一个都别省。useSSLfalse、serverTimezone、allowPublicKeyRetrieval这三个是高频报错的重灾区写全了能省掉大量排查时间。第三Nacos 3.x 的启动参数和 2.x 有差异别照搬旧教程。尤其是-m standalone和控制台地址旧教程里的写法在 3.0.2 上不一定对。第四启动失败先看日志别急着重装。logs/start.out和logs/nacos.log里的信息比控制台窗口一闪而过的内容有用得多。把日志看懂了大部分问题都能自己解决。第五验证持久化一定要重启一次。不重启你永远不知道数据到底存哪了。这个习惯能帮你提前发现配置没生效的问题避免在真正使用的时候踩雷。最后再分享一个小技巧把整个安装过程写成一个 checklist每装一台新机器就照着走一遍把遇到的报错和解决办法记在旁边。装到第三台的时候你基本就能闭着眼睛搞定而且遇到新问题也能快速定位。这套环境搭好之后后面接 Spring Cloud Alibaba、Dubbo 或者 K8s 的服务治理都会顺很多算是微服务本地开发的一个基础设施。