跳到主要内容

常见问题

本章节收录了在搭建和运行 Nukkit 服务器时的常见问题及解决方案。

服务器无法启动​

问题描述​

双击启动脚本后,窗口一闪而过或报错。

可能原因及解决方案​

1. Java 未安装或版本过低​

检查方法:

java -version

解决方案:

  • 确保已安装 Java 21 或更高版本
  • 参考 准备工作 章节重新安装 Java

2. JAR 文件名不匹配​

检查方法:

  • 查看启动脚本中的 JAR 文件名是否与实际文件名一致

解决方案:

  • 修改启动脚本中的文件名,或重命名 JAR 文件

3. JAR 文件损坏​

检查方法:

  • 查看文件大小是否异常 (正常约 10-20 MB)

解决方案:

  • 重新下载 Nukkit-MOT

4. 内存不足​

错误信息:

Could not reserve enough space for object heap

解决方案:

  • 减少启动脚本中的内存分配 (如 -Xmx512M)
  • 关闭其他占用内存的程序

玩家无法连接​

本地连接问题​

Windows 回环限制​

问题描述: 在同一台电脑上无法连接到服务器。

解决方案: 以管理员身份运行 PowerShell,执行:

CheckNetIsolation LoopbackExempt -a -n="Microsoft.MinecraftUWP_8wekyb3d8bbwe"

防火墙问题​

问题描述: 局域网或公网玩家无法连接。

解决方案:

Windows 防火墙:

  1. 打开 "Windows Defender 防火墙"
  2. 点击 "高级设置"
  3. 新建入站规则,允许 UDP 端口 19132

Linux (ufw):

sudo ufw allow 19132/udp

Linux (iptables):

sudo iptables -A INPUT -p udp --dport 19132 -j ACCEPT

端口被占用​

错误信息:

Address already in use

解决方案:

  • 检查是否有其他程序占用了 19132 端口
  • 修改 server.properties 中的 server-port 为其他端口

网易客户端无法连接​

问题描述: 使用网易我的世界客户端无法连接。

解决方案: 在 nukkit-mot.yml 中启用网易客户端支持:

netease-settings:
  client-support: true

NetherNet 玩家卡在"连接中"​

问题描述: 使用 NetherNet（WebRTC 传输，基岩版 1.26.50 起客户端默认）的玩家卡在"连接中"，或加入后立刻掉线。日志出现 NetherNet media may be unreachable: ... ICE attempts, 0 connected。

检查方法:

  • /status 中 NetherNet 的"接受的加入"在增长而 ICE 连通数恒为 0 —— 媒体 UDP 路径被阻断

解决方案:

  • 在防火墙放行 server-port 的 TCP（NetherNet 信令）
  • 放行媒体 UDP 端口的入站（防火墙/云安全组/端口转发）——默认媒体与 RakNet 共用 server-port 的 UDP 侧（19132），RakNet 本就要求放行；钉住独立端口（19134 等）时则必须显式放行。端口窗口、NAT 端口映射与 TURN 中继详见 server-udp-ports

插件问题​

插件加载失败 (红色)​

问题描述: 使用 plugins 命令时,插件名称显示为红色。

可能原因:

1. 版本不兼容​

  • 插件不支持当前 Nukkit 版本

解决方案:

  • 查找支持当前版本的插件
  • 更新 Nukkit 到插件要求的版本

2. 缺少依赖​

  • 插件依赖其他插件

解决方案:

  • 查看插件文档,安装所需的依赖插件

3. 配置文件错误​

  • 插件配置文件格式错误

解决方案:

  • 检查控制台的错误信息
  • 删除配置文件让插件重新生成
  • 参考插件文档修正配置

性能问题​

服务器卡顿​

可能原因:

1. 内存不足​

解决方案:

  • 增加启动脚本中的 -Xmx 值
  • 减少同时在线玩家数

2. 区块加载过多​

解决方案: 在 server.properties 中减小视距:

view-distance=6

3. 插件冲突或性能问题​

解决方案:

  • 逐个禁用插件,找出问题插件
  • 更新或替换性能较差的插件

世界/数据问题​

世界损坏​

问题描述: 服务器无法加载世界或报错。

解决方案:

  1. 停止服务器
  2. 备份 worlds 文件夹
  3. 尝试删除 worlds/world/db 中的锁文件
  4. 如果无法修复,从备份恢复

数据丢失​

预防措施:

  • 定期备份 worlds 文件夹
  • 正确关闭服务器 (使用 stop 命令而非强制关闭)

其他问题​

控制台乱码​

Windows 用户: 在启动脚本开头添加:

chcp 65001

无法执行命令​

问题描述: 在控制台输入命令无响应。

解决方案:

  • 检查是否有大量错误信息刷屏
  • 尝试重启服务器
  • 检查是否是插件导致的问题

获取帮助​

如果以上方案无法解决你的问题:

  1. 查看完整的服务器日志 (logs 文件夹)
  2. 搜索错误信息
  3. 在 GitHub Issues 提问
  4. 加入社区讨论群寻求帮助
提问时请提供
  • 服务器版本
  • Java 版本
  • 操作系统
  • 完整的错误日志
  • 问题复现步骤