简介这是一份面向网络编程初学者与嵌入式调试人员的 Qt 网络调试工具源码覆盖 TCP 客户端、TCP 服务端、UDP 服务端与 UDP 客户端四种模式可解决日常联调中收发数据、模拟设备响应等需求。压缩包共 35 个文件约 263KB以 cpp 与 h 源文件为核心实现配合 ui 界面文件、pri 工程模块、qm 中文翻译及 txt 配置样例目录按 api、form、other 分层整理结构清晰便于二次开发。目前已有 7842 人学习下载。功能上支持十六进制与 ASCII 收发、定时自动发送、多客户端并发连接并能从配置文件恢复上次界面设置与常用发送数据还可依据 device.txt 模拟设备自动回复适合用来理解 Qt 网络模块的单线程事件驱动写法与界面配置持久化思路。1. 一个调试工具为什么值得自己写一遍手头有个嵌入式板子要联调串口通了网口还没验证。你打开系统自带的网络工具发现它只能当客户端想模拟一个服务端等设备主动上报就得再找别的软件换个场景要发 UDP 广播又得开第三个窗口。来回切换、参数对不上、日志散落各处一个下午就耗在工具本身而不是业务上。这个项目解决的就是这件事用 Qt 把 TCP 客户端、TCP 服务端、UDP 服务端三种角色塞进同一个界面收发数据、连接管理、十六进制显示、日志留存都在一处完成。适合正在做设备联调、协议验证、上位机原型的开发者也适合想拿一个完整 Qt 网络编程范例来改自己工具的人。它不追求大而全胜在结构清楚、每一层都能拆开看、拆开改。2. 技术选型与工程骨架为什么是 Qt Widgets 加 QTcpSocket2.1 选型逻辑不引入额外依赖的最小闭环这个项目的核心诉求是“跨平台 网络 IO 图形界面”三者要在一个工程里闭环。Qt 恰好把这三块都覆盖了QTcpSocket、QTcpServer、QUdpSocket属于 Qt Network 模块随 Qt 一起装不需要额外拉第三方库界面用 Qt Widgets控件拖一拖就能出原型比手写布局快得多。常见做法是用 qmake 的.pro文件管理工程因为它的依赖声明最直观几行就够QT core gui network greaterThan(QT_MAJOR_VERSION, 4): QT widgets TARGET NetDebugAssistant TEMPLATE app CONFIG c11 SOURCES main.cpp \ mainwindow.cpp \ tcpclientpage.cpp \ tcpserverpage.cpp \ udpserverpage.cpp HEADERS mainwindow.h \ tcpclientpage.h \ tcpserverpage.h \ udpserverpage.hQT network是命门漏了这一行编译时所有 socket 类都会报未定义。CONFIG c11保证能用上 lambda 连接信号槽后面写回调会舒服很多。如果团队已经全面转向 CMake把上面这段等价翻译成find_package(Qt5 COMPONENTS Widgets Network REQUIRED)加target_link_libraries即可逻辑不变。2.2 目录结构按“角色”切页而不是按“功能”堆代码工程骨架我一般会按网络角色分文件而不是把所有槽函数塞进一个 MainWindow。这样每个页面自己管自己的 socket 生命周期互不干扰NetDebugAssistant/ ├── NetDebugAssistant.pro ├── main.cpp ├── mainwindow.h / mainwindow.cpp # 主窗口只负责 Tab 容器和全局状态 ├── tcpclientpage.h / .cpp # TCP 客户端连接、断开、收发 ├── tcpserverpage.h / .cpp # TCP 服务端监听、多连接管理、广播下发 ├── udpserverpage.h / .cpp # UDP 服务端绑定端口、收包、回包 └── common/ ├── hexutils.h / .cpp # 十六进制与字符串互转 └── logger.h / .cpp # 统一日志落盘主窗口只做一件事用QTabWidget把三个页面挂上去再提供一个全局的“清空日志”“保存日志”入口。页面之间不直接互相引用需要共享配置比如默认编码、是否自动滚动时走主窗口的信号中转。这种切法在后期加“TCP 客户端多开”“UDP 组播”时特别省事新开一个页面文件就行不用动老代码。2.3 信号槽是网络层的“总线”Qt 网络类的异步特性决定了你不能用阻塞读。QTcpSocket在数据到达时发readyRead()连接状态变化时发connected()/disconnected()/errorOccurred()。页面构造函数里把这些信号一次性接好后面所有逻辑都是事件驱动// tcpclientpage.cpp 构造函数片段 m_socket new QTcpSocket(this); connect(m_socket, QTcpSocket::connected, this, [this]() { m_btnConnect-setText(QStringLiteral(断开)); appendLog(QStringLiteral([系统] 已连接到 %1:%2) .arg(m_editHost-text()).arg(m_spinPort-value())); }); connect(m_socket, QTcpSocket::readyRead, this, TcpClientPage::onReadyRead); connect(m_socket, QTcpSocket::errorOccurred, this, [this](QAbstractSocket::SocketError) { appendLog(QStringLiteral([错误] %1).arg(m_socket-errorString())); });这里用 lambda 而不是单独写槽函数是因为连接成功后的界面更新逻辑很短就地写可读性更好readyRead的处理可能较长单独抽成成员函数方便复用和调试。errorOccurred是 Qt 5.15 之后的信号名老版本叫error迁移时注意改。参数上QAbstractSocket::SocketError枚举值本身信息有限真正有用的是errorString()日志里一定要打出来否则排查时只能看到“连接失败”四个字等于没有信息。3. 三个角色的核心实现从连接到收发的完整链路3.1 TCP 客户端连接、发送与粘包处理客户端的连接动作很简单难的是收数据。TCP 是字节流一次readyRead可能收到半条消息也可能收到两条半。项目里如果只是做调试工具常见做法是提供一个“按行显示”和“按原始字节显示”的切换把粘包问题交给使用者判断而不是强行拆包void TcpClientPage::onReadyRead() { QByteArray data m_socket-readAll(); if (data.isEmpty()) return; if (m_chkHexDisplay-isChecked()) { // 十六进制模式逐字节转成 AA BB CC 形式便于看协议头 appendLog(QStringLiteral([收] %1).arg(HexUtils::toHexString(data))); } else { // 文本模式按 UTF-8 解码非法字节用替换符兜底避免界面乱码崩溃 QString text QString::fromUtf8(data); appendLog(QStringLiteral([收] %1).arg(text)); } m_totalRecv data.size(); updateCounter(); }readAll()会把当前缓冲区里所有可读字节一次性取走这是调试工具的正确姿势——不要试图在readyRead里循环readLine()因为对端不一定发换行符。HexUtils::toHexString内部用data.toHex( ).toUpper()一行就能实现注意toHex的分隔符参数在 Qt 5.9 之后才支持老版本得手写循环。发送侧则要处理“发送失败”的情况void TcpClientPage::onSendClicked() { if (m_socket-state() ! QAbstractSocket::ConnectedState) { appendLog(QStringLiteral([提示] 未连接发送被忽略)); return; } QByteArray payload m_chkHexSend-isChecked() ? HexUtils::fromHexString(m_editSend-toPlainText()) : m_editSend-toPlainText().toUtf8(); qint64 written m_socket-write(payload); if (written -1) { appendLog(QStringLiteral([错误] 发送失败%1).arg(m_socket-errorString())); } else { appendLog(QStringLiteral([发] %1 字节).arg(written)); } }write()返回实际写入缓冲区的字节数返回 -1 才是真失败返回小于payload.size()的情况在 Qt 里通常不会出现内部会缓冲但严谨起见可以判断一下。十六进制发送前要做合法性校验fromHexString遇到非法字符会返回空数组界面上要给出提示否则用户会以为“发出去了但对方没收到”白白排查半天。3.2 TCP 服务端多连接管理与定向下发服务端比客户端多一层要同时管理多个客户端连接。QTcpServer只负责监听新连接通过newConnection信号交出来每个连接是一个独立的QTcpSocket。项目里用一个QListQTcpSocket*维护在线连接界面上用列表展示对端地址发送时可以选择“广播给所有”或“只发给选中项”void TcpServerPage::onNewConnection() { while (m_server-hasPendingConnections()) { QTcpSocket *client m_server-nextPendingConnection(); m_clients.append(client); // 每个连接单独接信号注意用 client 作为上下文断开后自动失效 connect(client, QTcpSocket::readyRead, this, [this, client]() { QByteArray data client-readAll(); appendLog(QStringLiteral([%1:%2] %3) .arg(client-peerAddress().toString()) .arg(client-peerPort()) .arg(QString::fromUtf8(data))); }); connect(client, QTcpSocket::disconnected, this, [this, client]() { m_clients.removeOne(client); client-deleteLater(); // 关键延迟删除避免在信号回调里析构自己 refreshClientList(); }); refreshClientList(); } }hasPendingConnections()加while是标准写法一次newConnection可能对应多个排队连接。deleteLater()不能换成delete因为当前还在这个 socket 的信号回调栈里直接析构会导致悬空指针这是 Qt 网络编程里最常见的翻车点之一。广播下发时遍历m_clients对每个 socket 调write()注意判断state() ConnectedState已经断开的连接可能还残留在列表里disconnected信号尚未处理直接写会触发错误。3.3 UDP 服务端绑定、收包与回包UDP 没有连接概念核心就三件事绑定端口、收数据报、按需回包。QUdpSocket的readyRead语义和 TCP 类似但每次读的是一个完整数据报用readDatagram能同时拿到发送方地址和端口void UdpServerPage::onReadyRead() { while (m_socket-hasPendingDatagrams()) { QByteArray datagram; datagram.resize(int(m_socket-pendingDatagramSize())); QHostAddress sender; quint16 senderPort 0; m_socket-readDatagram(datagram.data(), datagram.size(), sender, senderPort); appendLog(QStringLiteral([收] %1:%2 - %3) .arg(sender.toString()).arg(senderPort) .arg(QString::fromUtf8(datagram))); // 勾选“自动回包”时把收到的内容原样发回去方便验证链路 if (m_chkEcho-isChecked()) { m_socket-writeDatagram(datagram, sender, senderPort); } } }pendingDatagramSize()必须在readDatagram之前调用且resize要转成int否则大包场景下会有符号问题。while (hasPendingDatagrams())保证一次信号把缓冲区里所有数据报都取完避免遗漏。绑定端口时用bind(QHostAddress::AnyIPv4, port)如果只想本机测试就绑LocalHost绑定失败要检查端口是否被占用errorString()会给出明确原因。4. 避坑与排查联调时最容易翻车的五个点4.1 现象客户端显示已连接但发数据对方收不到原因通常是发送时 socket 状态已经变了或者发送的是空 payload。write()对空数组返回 0不报错日志里看起来“发了”实际什么都没发。解决发送前判断payload.isEmpty()并提示同时在write()后调flush()强制推送到内核缓冲区调试工具里这个动作很有必要否则数据可能滞留在 Qt 内部缓冲。4.2 现象服务端收到连接后界面列表不刷新或出现重复项原因是newConnection里没有用while循环取完所有 pending 连接或者refreshClientList()在循环内被多次调用导致重复插入。解决循环外统一刷新一次列表控件每次刷新前先clear()不要用增量追加调试工具的数据量很小全量刷新最不容易出错。4.3 现象十六进制显示出现多余空格或大小写混乱QByteArray::toHex()不带分隔符时输出连续字符串带分隔符参数是 Qt 5.9 才有的。如果工程要兼容老版本自己写循环每字节QString(%1).arg(uchar, 2, 16, QChar(0)).toUpper()并在字节间手动加空格。解决把转换逻辑收进HexUtils一个文件所有页面统一调用避免各写各的导致格式不一致。4.4 现象关闭页面或断开连接时程序崩溃典型原因是 socket 的disconnected回调里直接delete了 socket而 Qt 的事件循环还在处理该 socket 的其他事件。解决一律用deleteLater()页面析构时先disconnect所有信号再关闭 socket顺序反了会触发回调访问已析构的成员。血泪经验是网络相关的析构一定要放在最后且加if (m_socket)判空。4.5 现象UDP 收不到包但抓包工具显示数据已到达先查绑定地址绑了LocalHost就只能收本机回环的包外部设备发来的收不到。再查防火墙是否放行该端口。最后查是否在readyRead里只读了一次——UDP 可能一次信号对应多个数据报必须while循环。解决绑定用AnyIPv4收包用循环日志里打印发送方地址三件事做完基本能定位。5. 二次开发把它改成你自己的协议调试器拿到这个工程后最值钱的改造方向不是加界面皮肤而是把“通用收发”变成“懂你协议的调试器”。我的做法是抽一个ProtocolCodec接口让每个页面持有一个编解码器指针class ProtocolCodec { public: virtual ~ProtocolCodec() default; // 把原始字节解析成可读结构解析失败返回 false 并给出原因 virtual bool decode(const QByteArray raw, QString pretty, QString err) 0; // 把用户输入的文本编码成待发送字节 virtual QByteArray encode(const QString input) 0; };然后针对自己的协议实现一个子类比如带 2 字节长度头 1 字节命令字的格式decode里先校验长度再拆字段pretty输出成“命令0x03 载荷...”。页面里只调接口不关心具体协议换协议就是换一个实现类界面代码一行不动。验证方法很直接造三组数据——正常包、长度不足的残包、长度超标的异常包分别走一遍decode看日志输出是否符合预期再用真实设备发一轮对比抓包结果。另一个实用改造是日志结构化。现在日志是纯文本追加改成每行带时间戳、方向、对端地址的 JSON 行落盘后用脚本一过滤就能统计“哪个命令发得最多”“哪次请求没回包”。logger.h里加一个log(Direction dir, const QString peer, const QByteArray payload)重载即可改动量很小但排查效率提升明显。还有一个容易忽略的点把默认参数做成可保存的配置。主机地址、端口、编码方式、是否十六进制这些每次启动都要重填很烦。用QSettings在关闭时存、启动时读十行代码的事。我一般会在closeEvent里统一保存而不是每个控件单独接信号避免漏存。从那以后我每次写这类调试工具都强制先把HexUtils和Logger两个基础件写出来再动界面因为联调时真正救命的不是好看的布局而是“这条数据到底是谁在什么时候发出来的”能一眼看清。希望这个工程的拆解能帮到你拿去改成自己顺手的样子比直接用现成工具更值。本文还有配套的精品资源点击获取