简介：这是一份面向C++初学者与QT开发进阶者的网络联机五子棋实战项目源码，聚焦游戏网络通信与跨平台客户端开发能力训练。资源完整实现公网级实时对局功能，含服务端（Linux下Socket实现）与客户端（Windows下QT界面+Socket通信）双模块，覆盖网络编程、GUI设计、多线程协同等核心知识点，适用于课程设计、毕业设计及小型游戏开发练手。压缩包共28个文件，含6个核心cpp源文件、4个h头文件支撑逻辑分层，3个ui文件定义QT界面布局，9个png/jpg资源图用于按钮、棋子与背景，辅以pro工程配置、qrc资源注册及makefile编译脚本，整体仅559KB，轻量易读易调试。目前已有1399人学习下载，读者可直接编译运行，获得完整可联网对战的五子棋系统、清晰的客户端-服务端通信流程注释、QT界面与网络模块解耦的目录结构，以及适配双平台的Socket封装实践参考。
1. 网络联机五子棋小游戏源码（C++）：不是玩具，是TCP通信+Qt事件循环+状态同步的完整工程切片
你手头这份「网络联机五子棋小游戏源码（C++）」，不是教学Demo里那种点开就赢、关掉就丢的单机彩蛋。它是一套真实跑通局域网P2P对战的可执行工程——客户端能发起连接、服务端能接受两个玩家、落子动作实时同步、断线重连有状态回滚、悔棋逻辑走的是服务端权威校验而非客户端信任。我去年在某高校嵌入式实验室带学生做课程设计时，就拿它当底层框架改出了一个支持NAT穿透的轻量级对战模块。它适合三类人：刚学完Qt信号槽想落地练手的C++新手；需要快速验证网络状态同步模型的中级开发者；或者正在为毕业设计找“有网、有UI、有交互、不空洞”的开源基座的本科生。别被“小游戏”三个字骗了——它的GameSession类封装了完整的回合状态机，NetworkManager里藏着TCP粘包处理和心跳保活，而BoardModel的坐标序列化方式，直接决定了你在Wireshark里抓包时能不能一眼看懂协议字段。这不是玩具，是能拆、能改、能压进实际项目里的技术切片。
2. 从零编译运行：Qt5.15 + CMake构建链与关键依赖项确认
2.1 源码结构解析：看清四个核心目录的职责边界
拿到压缩包后，先解压观察顶层目录结构。典型布局如下（不同作者命名略有差异，但功能模块高度一致）：
gobang_network/ ├── src/ # 主体逻辑：网络层、游戏规则、UI控制器 │ ├── core/ # GameBoard、PlayerState、MoveValidator等纯逻辑类 │ ├── network/ # TcpClient、TcpServer、ProtocolParser（含序列化/反序列化） │ └── ui/ # MainWindow、GameWidget、ConnectionDialog等Qt界面类 ├── resources/ # qrc资源文件、图标、音效（部分版本含） ├── CMakeLists.txt # 根构建脚本（重点！决定Qt模块加载） └── README.md # 作者写的简要说明（常含编译命令示例）提示：不要急着双击
.pro文件用Qt Creator打开——这份源码大概率是CMake驱动的。Qt Creator虽支持CMake项目，但若CMakeLists.txt里指定了find_package(Qt5 REQUIRED COMPONENTS Core Widgets Network)却漏了Gui，或Qt版本写成5.12而你装的是5.15，就会卡在#include <QPainter>报错。先确认Qt安装路径和版本号。
2.2 Qt环境准备：为什么必须用Qt5.12～5.15而非6.x
该工程大量使用QHostAddress::setAddress()、QTcpSocket::waitForConnected()等阻塞式API，而Qt6默认禁用阻塞调用（需显式启用QT_NO_KEYWORDS宏），且QDataStream序列化格式在Qt6中做了ABI变更。实测Qt6.2编译可通过，但运行时QByteArray在网络传输中出现长度错位——原因在于Qt5默认用QDataStream::Qt_5_6协议，Qt6升为Qt_6_0，导致服务端发0x00000005（5字节）被客户端解析成0x0000000000000005（8字节）。血泪经验：用qmake -v查本地Qt版本，若为6.x，请降级到5.15.2（官方长期支持版），或手动在CMakeLists.txt中添加：
set(CMAKE_CXX_STANDARD 11) add_definitions(-DQT_NO_KEYWORDS) # 允许使用signals/slots等关键字但更稳妥的做法是换Qt5——毕竟作者没为Qt6适配过QAbstractSocket::flush()的语义变更。
2.3 CMake构建全流程：从配置到可执行文件生成
进入源码根目录，按顺序执行以下命令（Linux/macOS）：
# 1. 创建构建目录（避免污染源码） mkdir build && cd build # 2. 配置CMake（关键：指定Qt5路径！） cmake -DCMAKE_PREFIX_PATH=/opt/Qt5.15.2/5.15.2/gcc_64 .. # 3. 编译（-j4表示4线程，根据CPU核心数调整） make -j4 # 4. 安装到本地bin（可选，方便后续调试） make installWindows用户请用cmake-gui，在Where is the source code填源码路径，Where to build the binaries填build目录，点击Configure后，在弹出窗口中选择Visual Studio 16 2019（或对应VS版本）和Use default native compilers，再点Generate。若提示Could NOT find Qt5，点击Add Entry，新增Qt5_DIR变量，值为C:/Qt/5.15.2/msvc2019_64/lib/cmake/Qt5。
参数说明：
CMAKE_PREFIX_PATH是Qt5安装根目录，gcc_64是Linux下编译器工具链名（macOS为clang_64，Windows为msvc2019_64）。若路径错误，CMake会报find_package(Qt5 REQUIRED COMPONENTS ...)失败，此时需用find /opt/Qt* -name "Qt5Config.cmake"反向定位真实路径。
2.4 运行双实例验证：服务端监听与客户端连接的时序要点
编译成功后，生成两个可执行文件：gobang_server（服务端）和gobang_client（客户端）。必须严格按此顺序启动：
# 终端1：启动服务端（监听本机3000端口） ./gobang_server --port 3000 # 终端2：启动第一个客户端（连接localhost:3000） ./gobang_client --host 127.0.0.1 --port 3000 # 终端3：启动第二个客户端（同样连接同一地址） ./gobang_client --host 127.0.0.1 --port 3000注意：服务端启动后会打印Server listening on 0.0.0.0:3000，此时才可启动客户端。若客户端报Connection refused，先netstat -tuln | grep 3000确认端口是否被占用；若服务端无输出，检查防火墙是否拦截（Linux用sudo ufw status，macOS用sudo pfctl -s rules）。
3. 网络通信层深度拆解：TCP粘包处理、协议设计与心跳机制实现
3.1 协议帧结构：为什么用自定义Header而非JSON？
该工程未采用HTTP或JSON，而是定义二进制协议帧，结构如下：
| 4字节Header | N字节Payload | |-------------|--------------| | uint32_t len| char data[len] |Header为网络字节序（大端）的uint32_t，表示Payload长度。Payload内为QVariantMap序列化后的QByteArray，键名固定为{"type":"move","x":3,"y":4,"player":1}或{"type":"disconnect"}。
选型理由：JSON解析需第三方库（如QJsonDocument）且字符串解析耗CPU；而QDataStream直接序列化QVariantMap，二进制体积小、解析快、无编码歧义。实测1000次落子消息，二进制帧平均28字节，JSON帧平均67字节，且后者需额外做QString::toUtf8()转换。
3.2 粘包处理：QByteArray累积缓冲与peek()的精准截取
TcpClient::readyRead()槽函数中，核心逻辑是：
void TcpClient::onReadyRead() { m_buffer.append(socket->readAll()); // 累积所有数据 while (m_buffer.size() >= sizeof(quint32)) { quint32 header = 0; QDataStream stream(&m_buffer); stream >> header; // 读取Header（不移动buffer指针） if (m_buffer.size() < sizeof(quint32) + header) break; // 数据不足，等待下次 QByteArray payload = m_buffer.mid(sizeof(quint32), header); // 截取Payload m_buffer.remove(0, sizeof(quint32) + header); // 清除已处理数据 parsePayload(payload); // 解析业务逻辑 } }关键点：
stream >> header只是读取前4字节，m_buffer本身未被修改；mid()和remove()才是真正的截取操作。若误用socket->read(header+4)，会导致QDataStream读取位置错乱——这是新手最常翻车的点。
3.3 心跳保活：QTimer间隔发送ping与超时断连策略
服务端每10秒向每个客户端发送{"type":"ping"}，客户端收到后立即回复{"type":"pong"}。客户端侧用QTimer监控：
// Client类中 QTimer *m_heartbeatTimer = new QTimer(this); connect(m_heartbeatTimer, &QTimer::timeout, this, [this]() { if (m_lastPongTime.secsTo(QDateTime::currentDateTime()) > 30) { emit connectionLost(); // 触发断连信号 socket->close(); } }); m_heartbeatTimer->start(5000); // 每5秒检查一次m_lastPongTime在收到pong时更新。注意：不能只靠TCP Keepalive（socket->setSocketOption(QAbstractSocket::KeepAliveOption, 1)），因为其默认超时长达2小时，无法满足游戏级实时性要求。
3.4 断线重连：状态同步的“后悔药”机制
当客户端A断线重连时，服务端不重建棋盘，而是发送全量状态：
{ "type": "resync", "board": [0,0,0,1,0,0,0,2,...], // 15x15=225个整数，0空/1黑/2白 "current_player": 1, "last_move": {"x":3,"y":4} }客户端收到后，直接覆盖本地BoardModel数据。玄学细节：重连时服务端会暂停接收新落子，直到resync完成，避免状态撕裂——这个锁在GameSession::handleReconnect()里用QMutex保护，若忘记加锁，会出现“重连后看到对方多下了一步”的诡异现象。
4. 游戏逻辑与UI协同：Qt信号槽驱动的状态流转与线程安全边界
4.1 棋盘状态管理：BoardModel的不可变性设计与QVector优化
BoardModel不直接暴露二维数组，而是提供at(x,y)只读访问和placeStone(x,y,player)写入接口：
class BoardModel : public QObject { Q_OBJECT private: QVector<quint8> m_data; // 一维存储，索引=x+y*15，节省内存且缓存友好 public: quint8 at(int x, int y) const { return (x>=0&&x<15&&y>=0&&y<15) ? m_data[x+y*15] : 0; } bool placeStone(int x, int y, quint8 player) { if (at(x,y) != 0) return false; // 已有子，拒绝 m_data[x+y*15] = player; emit stonePlaced(x, y, player); // 发射信号通知UI return true; } };为什么不用
QVector<QVector<quint8>>？二维QVector每次resize()会触发多次内存分配，而一维QVector只需一次reserve(225)，且CPU缓存命中率更高。实测10万次随机落子，一维方案耗时12ms，二维方案23ms。
4.2 UI响应链：从鼠标点击到网络发送的七步穿透
用户点击棋盘某格，触发流程如下：
GameWidget::mousePressEvent()捕获坐标 →- 调用
BoardModel::placeStone(x,y,currentPlayer)→ BoardModel校验合法性，成功则发射stonePlaced(x,y,player)→GameController连接此信号，调用NetworkManager::sendMove(x,y,player)→NetworkManager构造QVariantMap并序列化为QByteArray→QDataStream写入Header+Payload到QTcpSocket→QTcpSocket::write()发出，由内核TCP栈发送
关键约束：步骤2的placeStone()必须在主线程执行（Qt GUI线程），而步骤6的write()虽是异步，但QByteArray序列化必须在主线程完成——若把序列化放到QThread，QVariantMap跨线程传递会崩溃。
4.3 多线程安全：QMetaObject::invokeMethod在非GUI线程更新UI
网络接收逻辑在QTcpSocket::readyRead()中执行，属于IO线程（非GUI线程）。当收到对手落子消息，需更新己方棋盘UI，但GameWidget::update()只能在GUI线程调用。解决方案：
// 在NetworkManager中（非GUI线程） void NetworkManager::onMoveReceived(int x, int y, int player) { // 通过invokeMethod跨线程调用UI方法 QMetaObject::invokeMethod( m_gameWidget, [this, x, y, player]() { m_gameWidget->renderStone(x, y, player); }, Qt::QueuedConnection ); }Qt::QueuedConnection确保lambda在GUI线程事件循环中执行。若误用Qt::DirectConnection，程序会直接崩溃——这是Qt多线程最经典的坑。
4.4 悔棋实现：服务端权威校验与客户端本地回滚的配合
悔棋不是简单undo()，而是分三步：
- 客户端点击“悔棋” → 发送
{"type":"undo_request"}给服务端 - 服务端校验：当前回合是否允许悔棋（通常限定开局10步内）、双方是否都同意（需广播
undo_vote） - 服务端批准后，广播
{"type":"undo_commit","step_id":123}，客户端收到后清除最后一步并重绘
注意：客户端本地
BoardModel不保存历史步数，悔棋时服务端必须下发step_id，客户端据此从QVector中删除对应坐标——否则会出现“A悔棋后B棋盘没变”的状态不一致。
5. 避坑指南：五个真实踩过的雷与绕过方案
5.1 现象：客户端连接服务端后立即断开，日志显示socket error: Connection reset by peer
原因：服务端QTcpServer::nextPendingConnection()返回的QTcpSocket未设置setSocketOption(QAbstractSocket::KeepAliveOption, 1)，且客户端发送数据后服务端未及时read()，导致TCP栈认为连接异常。
解决：在服务端onNewConnection()槽函数中，对新socket强制设置：
socket->setSocketOption(QAbstractSocket::KeepAliveOption, 1); socket->setSocketOption(QAbstractSocket::LowDelayOption, 1); // 关闭Nagle算法5.2 现象：两人对战时，一方落子后另一方棋盘无反应，但Wireshark能看到数据包
原因：QDataStream序列化QVariantMap时，若QVariantMap中混用QString和int，Qt5默认用QDataStream::Qt_5_6协议，但某些编译器（如GCC 11）对QVariant的RTTI处理有偏差，导致反序列化失败。
解决：统一用QVariant::fromValue()构造，避免隐式转换：
// 错误写法（可能触发隐式转换） map["x"] = 3; // 正确写法（显式指定类型） map["x"] = QVariant::fromValue(3); map["player"] = QVariant::fromValue(static_cast<quint8>(1));5.3 现象：Qt Creator调试时，QTcpSocket::state()始终返回UnconnectedState，但connectToHost()已调用
原因：connectToHost()是异步函数，调用后立即返回，状态切换需等待事件循环。若在connectToHost()后立刻查state()，必然为UnconnectedState。
解决：必须连接connected()信号：
connect(socket, &QTcpSocket::connected, []() { qDebug() << "Connected successfully!"; }); socket->connectToHost("127.0.0.1", 3000); // 此处不能查state()！5.4 现象：macOS上编译通过，但运行时报dyld: Library not loaded: @rpath/Qt5Widgets.framework/Versions/5/Qt5Widgets
原因：macOS的动态库路径未正确绑定，@rpath指向错误位置。
解决：用install_name_tool修复（在make install后执行）：
install_name_tool -add_rpath @executable_path/../Frameworks ./gobang_client install_name_tool -change "@rpath/Qt5Widgets.framework/Versions/5/Qt5Widgets" \ "@executable_path/../Frameworks/Qt5Widgets.framework/Versions/5/Qt5Widgets" \ ./gobang_client5.5 现象：Windows上双击gobang_client.exe无窗口，任务管理器可见进程但立即退出
原因：缺少Qt平台插件（如qwindows.dll），导致QApplication初始化失败。
解决：将Qt安装目录下的plugins/platforms/qwindows.dll复制到可执行文件同级目录的platforms/子目录中：
gobang_client.exe └── platforms/ └── qwindows.dll验证命令：windeployqt --no-translations --no-system-d3d-compiler gobang_client.exe（Qt自带工具自动部署）。
6. 进阶技巧：用Wireshark逆向协议、添加AI对战模块与性能压测方法
6.1 Wireshark抓包分析：三步定位协议字段含义
当网络行为异常时，Wireshark是最硬核的排查工具。以落子消息为例：
- 过滤TCP流：启动服务端和客户端，用Wireshark抓
tcp.port == 3000，过滤出一条TCP流 - 定位二进制帧：在数据包详情中展开
Transmission Control Protocol→Data，右键Data→Follow→TCP Stream - 解析Header+Payload：流中首4字节为Header（如
00 00 00 1a= 26十进制），后续26字节即Payload。将其粘贴到十六进制编辑器（如HxD），转为ASCII可见{"type":"move","x":3,"y":4,"player":1}
技巧：若Payload是乱码，说明
QVariantMap序列化用了QDataStream二进制格式（非文本）。此时需用Qt代码反向解析：新建测试工程，QDataStream stream(&byteArray); QVariantMap map; stream >> map; qDebug() << map;
6.2 接入简易AI：Minimax算法替换Player类的makeMove()
原工程中Player类负责人类输入，可继承它创建AIPlayer：
class AIPlayer : public Player { Q_OBJECT public: explicit AIPlayer(QObject *parent = nullptr) : Player(parent) {} QPoint makeMove(const BoardModel *board) override { // 简化版：遍历所有空位，选得分最高者 int bestScore = -1000; QPoint bestPos(-1,-1); for (int x = 0; x < 15; ++x) { for (int y = 0; y < 15; ++y) { if (board->at(x,y) == 0) { int score = evaluatePosition(board, x, y, m_playerId); if (score > bestScore) { bestScore = score; bestPos = QPoint(x,y); } } } } return bestPos; } private: int evaluatePosition(const BoardModel *board, int x, int y, int player) { // 实现五子连珠评分：活四=1000，冲四=500，活三=100... return 0; // 此处补全评分逻辑 } };在GameController中，当检测到AI玩家时，调用aiPlayer->makeMove(board)获取坐标，再走正常落子流程。注意：AI计算必须在QThread中执行，避免阻塞GUI线程——否则点击“开始AI对战”后界面假死。
6.3 性能压测：用ab模拟百人并发连接与落子延迟统计
服务端性能瓶颈常在连接数和消息吞吐。用Apache Bench模拟压力：
# 模拟100个客户端，每个建立10次连接，每次发送1个落子请求 ab -n 1000 -c 100 -p move.json -T "application/octet-stream" http://127.0.0.1:3000/move其中move.json内容为：
{"type":"move","x":7,"y":7,"player":1}关键指标：关注
Time per request（平均延迟）和Failed requests（失败数）。若延迟>200ms或失败率>5%，需检查服务端QTcpServer::setMaxPendingConnections()是否过小（默认30），应设为server->setMaxPendingConnections(1000)。
6.4 跨平台部署检查表：Linux/macOS/Windows三端必验项
| 检查项 | Linux | macOS | Windows | 验证命令/方法 |
|---|---|---|---|---|
| Qt库路径是否硬编码 | ✅ | ✅ | ✅ | ldd ./gobang_client | grep Qt（Linux）otool -L ./gobang_client（macOS）dumpbin /dependents gobang_client.exe（Windows） |
| 图标资源是否加载 | ✅ | ✅ | ✅ | 启动后观察窗口左上角图标，或QFile::exists(":/icons/app.ico") |
| 中文路径兼容性 | ✅ | ✅ | ❌ | Windows下若Qt安装路径含中文，CMake会报CMake Error: Could not create named generator，必须重装到英文路径 |
| 防火墙放行端口 | ✅ | ✅ | ✅ | sudo ufw allow 3000（Ubuntu）sudo pfctl -f /etc/pf.conf（macOS）Windows Defender防火墙→高级设置→入站规则→新建规则→端口→TCP 3000 |
从那以后我每次接手C++ Qt网络项目，都会先用Wireshark抓3秒包，确认Header长度字段是否对齐、Payload是否可读；再写个10行Python脚本模拟客户端发100次{"type":"ping"}，看服务端QThreadPool是否撑得住。这些动作花不了5分钟，却能避开80%的“编译过了但跑不通”的玄学问题。希望帮到你。
本文还有配套的精品资源，点击获取
