常见问题

排查顺序永远是：先看 MC 控制台 → 再看 Bngeuit 控制台 → 最后看脚本。九成问题在第一步就能定位。

速查表

现象	大概原因	看哪一节
MC 控制台 连接 BngeuitBridge 失败	地址/端口错、服务端没起、防火墙	连不上
MC 控制台 认证失败！请检查 token 配置	两侧 token 不一致	认证失败
MC 控制台 clientId 已被占用	多台服务器撞名	client-id-冲突
有 已通过认证 但群里没消息	QQ 侧脚本没写/没启	通道通了但群里没反应
群里发命令没反应	前缀不对、白名单拦住、脚本没生效	群里发命令没反应
/bngeuitbridge status 一直超时	Bngeuit 侧没装 McBridgeStatus.nc	status 查询超时
每隔几十秒断一次	心跳超时设置不对	连接反复断开
控制台报 xxx.nc 的 enable 函数出现错误	脚本语法/import/漏 null	脚本加载失败
发了大消息却没到	超过 64 KB 上限	消息太大

连不上

[MC-BngeuitBridge] [WS] 连接 BngeuitBridge 失败: Connection refused

按顺序确认：

1. BngeuitBridge 真的启动了吗 —— Bngeuit 控制台要有 WebSocket 通道已启动，0.0.0.0:8765
2. 地址写对了吗 —— 同一台机器用 ws://localhost:8765；跨机必须写 Bngeuit 的内网/公网 IP，不能写 localhost
3. host 是不是 0.0.0.0 —— 服务端配成 127.0.0.1 时只接受本机连接，跨机必失败
4. 端口通不通 —— 在 MC 服务器上执行 telnet Bngeuit的IP 8765（Windows 用 Test-NetConnection 主机 -Port 8765），不通就是防火墙/安全组没放行
5. 端口是否被占用 —— Bngeuit 控制台若报端口绑定失败，换一个 port，MC 侧同步改

云服务器

阿里云/腾讯云的安全组、宝塔防火墙都要单独放行 TCP 8765，服务器本机的 firewalld/ufw 放行不算数。

认证失败

[MC-BngeuitBridge] [WS] BngeuitBridge 认证失败！请检查 token 配置

两侧 token 必须一字不差：大小写、前后空格、引号都算。注意 YAML 里 token: "abc" 和 token: abc 值是一样的，但 token: "abc " 末尾多了个空格就失败。

改完记得：MC 侧重载插件或重启服务器（/bngeuitbridge r 不重连通道），Bngeuit 侧 plugin reload BngeuitBridge。

client-id 冲突

[MC-BngeuitBridge] [WS] clientId "survival" 已被占用，请修改 config.yml

同一个 clientId 只能有一台服务器在线。可能是：

• 两台服务器都写了 survival → 改成不同名字
• 上一次的进程没退干净（比如服务器崩了但 Bngeuit 那边连接还没超时）→ 等 30 秒心跳检测掉线，或重启 BngeuitBridge
• 你在两台机器上跑了同一份服务端备份

通道通了但群里没反应

MC 侧看到 已通过 BngeuitBridge 认证，说明通道完全正常，问题在 QQ 侧：

1. QQ 侧脚本放了吗 —— Bngeuit 的 plugins/ 下要有对应的 .nc 脚本
2. 脚本加载了吗 —— Bngeuit 控制台会有脚本插件的启用日志；用 plugin list 或对应命令确认
3. depend 写了吗 —— 监听桥接事件的脚本必须 depend: ['BngeuitBridge']，否则脚本先加载、类还没注册，监听注册不上
4. 事件类名写对了吗 —— 必须用全限定名 cn.org.bukkit.bngeuit.bridge.event.BridgeMessageReceiveEvent
5. 群里没绑群 OpenID —— 脚本里 GROUP 还是示例值，消息发到了不存在的群

在 Bngeuit 侧脚本的监听器里先加一行日志（bngeuit.info(e.getType() + '/' + e.getAction())），能打出日志就说明前半段全通，问题只在发群消息那一步。

群里发命令没反应

检查点	说明
消息前缀	内置示例要求 /mccmd 开头，且是群内 @机器人 的消息
MC 侧脚本是否在跑	启动日志有 [CommandRelay]命令转发已启用
白名单	QQ 侧 ALLOWED_GROUPS 没包含这个群会静默忽略
黑名单	命令首词在任一侧黑名单里都会被拒
通道是否在线	断线时 MC 侧只记日志不执行，群里表现为一直没回执
服务器选择	CLIENT 写的是哪台？和 MC 侧的 client-id 必须一致

命令执行成功但看不到输出是正常的：命令输出只进服务器控制台，群里只回「执行成功」。

status 查询超时

[MC-BngeuitBridge] 正在查询 BngeuitBridge 状态...
（30 秒后）
[MC-BngeuitBridge] 查询失败: 请求超时

九成是没有装应答脚本。/bngeuitbridge status 只是发一条 bridge/status 请求，BngeuitBridge 自己不会回，必须由 Bngeuit 侧的 McBridgeStatus.nc 应答。

按顺序查：

1. Bngeuit 的 plugins/ 下有没有 McBridgeStatus.nc
2. 它加载成功了吗 —— Bngeuit 控制台要有 [桥接状态] 已启用（应答 bridge/status 查询）
3. 加载失败的常见原因：BngeuitBridge 没装（脚本声明了硬依赖）；两个脚本用了同一个 pluginName / package，后加载的会被拒；文件后缀不是 .nc
4. 脚本在跑但还是超时 —— 看 Bngeuit 控制台有没有 [桥接状态] 已回复状态查询: clientId=...：
   • 有这行 → 回程丢了，检查 MC 侧是不是正好在重连
   • 没有这行 → 请求没到 Bngeuit，说明通道其实没通，先看上一节

别拿 status 判断通道好坏

这个命令依赖对面有人应答，缺脚本就一定超时。判断连通性只看 MC 控制台那行 已通过 BngeuitBridge 认证，以及 Bngeuit 侧有没有 客户端认证成功。

连接反复断开

[WS] 与 BngeuitBridge 断开连接: 
[BridgeChannel] 5 秒后尝试重连...

• 每次都是固定间隔（如 30 秒）断：BngeuitBridge 的 heartbeat-interval 与 MC 侧 connection-timeout 配合不对。MC 侧的超时必须大于服务端心跳间隔，否则心跳还没到就被判定掉线。默认 30 / 60 是安全组合
• 断线后能自己连回来：这是网络抖动，属于正常重连，不用管
• 认证类错误断开后不再重连：这是刻意的，改配置重载插件
• 服务器卡顿严重时也会误判：TPS 极低会导致心跳线程被拖，适当调大 connection-timeout

脚本加载失败

[MC-BngeuitBridge] [CraneCore] xxx.nc 的 enable 函数出现错误: ...

（日志前缀写着 CraneCore 是历史遗留，实际就是本插件打的。）

按错误类型分：

报错	原因
编译期语法错误	nc 语法问题，对照 Nacre 文档
cannot find symbol / 类找不到	import 的类不存在，或拼错包名
Function1 相关的类型不匹配	监听器 lambda 末尾漏了 null
package 重复	两个脚本写了同一个 package，第二个会被拒
脚本数量对不上	文件后缀不是 .nc、放错目录、或编码不是 UTF-8

/bngeuitbridge r 之后控制台会打印 脚本 N个，先确认这个数字对不对。

消息太大

服务端单条消息上限默认 65536 字节（64 KB）。超了：

• 发的时候：服务端直接跳过不转发，日志 消息超过大小限制 (xxxxB > 65536B)，已跳过
• 收的时候：服务端回 message_too_large 并断开

data 里塞了整份配置文件、玩家背包、大量坐标列表最容易超。改成分页传、或者只传摘要。确实需要大消息就调大两侧配置（服务端 max-message-size）。

改配置不生效

改的是	生效方式
MC 侧 config.yml	重载插件 / 重启服务器。/bngeuitbridge r 只重载脚本
MC 侧 script/*.nc	/bngeuitbridge r
Bngeuit 侧 BngeuitBridge/config.yml	plugin reload BngeuitBridge / 重启 Bngeuit
Bngeuit 侧 .nc 脚本	对应的 plugin reload 脚本名 / 重启 Bngeuit

还需要更多信息

把这三样贴出来基本就能定位：

1. MC 控制台从 [MC-BngeuitBridge] 开头到报错的完整几行
2. Bngeuit 控制台 [BridgeChannel]、[Bridge:WS] 相关日志
3. 你的 config.yml（token 打码）

配置的含义逐个对照 安装与配置，消息字段对照 消息与事件。