在Godot中使用STUN实现NAT穿透时数据包无法接收问题排查

问题场景 #

在同一机器上运行两个Godot客户端测试NAT穿透流程：

1. 玩家A创建服务器，从STUN获取公网IP和端口（默认50000）并绑定该端口
2. 玩家B输入A的IP/端口点击连接，绑定自身STUN获取的端口（同样是50000），调用connect_to_host后阻塞在wait()等待数据包
3. 玩家A获取B的公网IP/端口后，调用connect_to_host并发送测试数据包
4. 预期B收到包后解除冻结，但实际从未触发，数据包未被接收

核心原因分析 #

1. 本地端口冲突 #

同一机器上，UDP端口无法被多个进程重复绑定（Godot默认未启用端口复用）。玩家A先绑定了50000端口，玩家B后续执行bind(50000)会直接失败，导致B的UDP套接字无法监听任何端口，自然无法接收数据包。这也是B需要点击两次连接的原因——第一次bind失败导致程序冻结，第二次操作未正确处理错误状态。

2. 阻塞式wait()的风险 #

PacketPeerUDP.wait()是阻塞方法，一旦套接字无法正常接收（比如绑定失败），会直接卡住程序，无法响应后续操作，也无法输出错误信息排查问题。

3. STUN公网IP的本地适配问题 #

本地测试时，STUN返回的公网IP可能是127.0.0.1或局域网IP，但端口冲突的问题会优先导致整个流程失效，掩盖其他潜在问题。

解决方案 #

1. 本地测试使用不同端口 #

给两个客户端分配不同的绑定端口，比如玩家A绑定50000，玩家B绑定50001，避免端口冲突。修改代码时可以让端口配置支持自定义，或者启动时自动选择可用端口。

2. 检查绑定操作的返回值 #

Godot的bind()方法会返回错误码，必须判断绑定是否成功，及时排查问题：

var bind_error = Singletons.peer.bind(Singletons.public_port)
if bind_error != OK:
    print("端口绑定失败: ", bind_error)
    # 这里可以添加重试逻辑，或者提示用户更换端口

3. 替换阻塞wait()为非阻塞轮询 #

改用get_available_packet_count()在帧更新中轮询数据包，避免程序冻结：

func _process(delta):
    if Singletons.peer.get_available_packet_count() > 0:
        var packet_data = Singletons.peer.get_packet()
        print("收到数据包: ", packet_data.get_string_from_ascii())

4. 本地测试跳过STUN #

本地环境不需要NAT穿透，直接使用127.0.0.1加上不同端口进行测试，避免STUN服务返回的公网IP在本地场景下的适配问题。

内容的提问来源于stack exchange，提问作者Big_Bad_E