Qt 網絡編程：Client 與 Server 跨機器連接失敗的排查清單

現象

本機 localhost 連接正常，換用服務器實際 IP 連接失敗。

排查步驟（由易到難）

1. 服務端監聽地址： 確認 QTcpServer::listen(QHostAddress::Any, port) 而非 QHostAddress::LocalHost。Any 綁定 0.0.0.0 接受所有網卡連接。
2. 防火牆/安全組：
   • 服務器作業系統防火牆放行該端口 (Windows: `netsh advfirewall firewall add rule ...`; Linux: `ufw allow port`/`firewall-cmd`)。
   • 雲服務器控制台安全組入站規則放行。
3. IP 版本匹配： 服務端綁 IPv4，客戶端用 IPv6 地址連會失敗。雙方統一用 IPv4 或雙棧。
4. 網絡可達性： 客戶端 ping 服務器 IP，telnet ip port / `nc -zv ip port` 測試端口通達。
5. 錯誤信號捕獲： 連接 QTcpSocket::errorOccurred (Qt5) 或 error (Qt6)，輸出 errorString() 具體原因（如 ConnectionRefusedError, HostUnreachableError）。
6. 代碼邏輯： 客戶端 connectToHost(ip, port) IP 字符串無多餘空格，端口為整數。

調試技巧

在服務端機器本地用另一終端 `telnet 本機IP 端口`，若本機跨網卡不通，則是服務端綁定/防火牆問題；若本機通但遠程不通，則是網絡/安全組問題。