简介：基于Qt框架构建的跨平台文件网络传输系统，面向具备一定C++基础的开发者和毕业设计学习者，演示Linux服务器与Windows 10客户端之间基于TCP的可靠文件传输。包体共23个文件，以C++源文件、头文件、Qt界面文件（.ui）及工程配置文件（.pro）为主，含少量备份与说明文档，压缩包仅20KB，代码精简适合快速通读。系统覆盖网络连接管理、文件分片校验、多线程分离I/O与界面响应等实现细节，服务端展现事件驱动或线程池并发模型，客户端支持拖拽上传与进度实时反馈，并预留SQLite持久化方案；工程组织方式、平台适配封装与备份文件结构也具备参考价值，可作为理解套接字编程与Qt跨平台编译的实践范本。当前已有73人学习，适合用于课程设计复盘或求职项目积累。

1. Qt框架做文件传输：不是只能写界面的GUI库

很多人听到Qt框架的第一反应是“做桌面界面”，但如果你把QTcpSocket、QTcpServer和跨平台编译这套组合用起来，会发现Qt做网络传输同样顺手。这份资源是一个典型的毕业设计题目：Linux服务器负责接收和落盘，Windows 10客户端负责选择文件和发送，两边跑同一套基于Qt框架的代码，只是编译目标和运行角色不同。整套系统不依赖第三方库，全用Qt自带的network模块，断点续传、实时进度、文件校验这些答辩加分点也都覆盖到了。适合准备Qt方向毕业设计、或者想快速搭一套跨平台文件传输原型的开发者。先说清楚一点：它不是什么大而全的网盘系统，而是把TCP长连接、分块发送、自定义报文协议这几个基本功串起来，做成一个能跑、能演示、能继续扩展的骨架。

2. 系统架构与传输协议：先定好包头，后面少改十次代码

2.1 整体角色划分与关键模块

这套系统分两端。服务器端运行在Linux上，启动后监听固定端口，维护一个QTcpSocket连接，接收客户端传过来的文件数据，边收边写入磁盘。客户端运行在Windows 10上，提供一个QWidget界面，让用户填服务器IP和端口、选择本地文件、设置保存路径，然后点按钮开始发送。

网络这块全部走Qt的network模块，不引入额外库。底层是TCP，这意味着两端之间是可靠字节流，丢包重传由内核完成，我们只需要关心“怎么从字节流里切出完整的业务数据”。这个切分逻辑就是协议设计的核心，也是整个项目里最容易翻车的地方。

模块划分上，服务器端拆成监听入口和连接处理两个对象，客户端拆成界面和传输逻辑两部分。传输逻辑用QFile读文件、QTcpSocket收发数据，界面只管进度条和状态文本。这样分离的好处是如果之后要加命令行版本，去掉界面部分就行，传输核心可以复用。

2.2 自定义二进制协议：固定包头加变长负载

我见过不少人拿着QDataStream直接整包发，小文件没问题，一到几百MB就各种对不齐。正确做法是设计一个固定长度的包头，后面跟上变长的文件名和数据区。

// protocol.h #pragma once #include <QtGlobal> // 命令字定义 enum UploadCmd { CMD_UPLOAD_INIT = 100, // 客户端声明要传文件 CMD_DATA_BLOCK = 110, // 数据块 CMD_UPLOAD_FINISH = 120, // 数据发送完毕 CMD_QUERY_OFFSET = 130, // 查询服务器已接收大小 CMD_RESPONSE_OFFSET = 200, // 服务器回复偏移量 CMD_ERROR_RESP = 300 // 错误响应 }; // 每个包的前 32 字节固定结构 struct PacketHeader { quint32 magic; // 固定魔数 0x5A5A5A5A，用来识别有效包 quint32 cmd; // 命令字 quint32 filenameLen; // 文件名字节长度 qint64 fileSize; // 文件总大小 quint32 blockIndex; // 块序号，从 0 开始 quint32 blockLen; // 本块数据长度 quint32 blockCrc32; // 块内数据 CRC32 校验 qint64 fileOffset; // 本块在文件中的偏移量 };

代码说明：包头一共32字节，其中magic是固定值0x5A5A5A5A。接收端每次先从缓冲区里读32字节，检查magic，如果对不上就说明后续解析状态已经错乱，直接断开连接重新来。filenameLen和fileSize都是发文件时已知的信息，服务器端拿到后可以先检查磁盘空间。blockCrc32是每个数据块的校验值，接收端算一遍，不一致就把整个块丢掉并请求重传。

参数说明：blockIndex从0递增，配合fileOffset就能支持乱序和续传。实际发送时按顺序发，但服务器端仍然以fileOffset为准来决定写入位置。CRC32这里承担的是“块级校验”，文件级别的完整性另用MD5在收尾时做，详见后面章节。

2.3 为什么不用现成协议

这个项目是毕业设计场景。用HTTP上传文件很简单，但答辩时你很难展示自己对网络传输的理解，因为HTTP协议把分块、响应、状态码这些事情全部封装掉了。FTP同样是个选项，不过FTP有控制连接和数据连接两条通道，还要处理被动模式端口协商，跨平台时两个被动模式命令互相不兼容的情况很常见。

自定义二进制协议的好处是你能明确说出“这一块是包头解析，这一块是粘包处理，这一块是校验逻辑”，每段代码对应一个技术点，阶段验收时很容易讲清楚。代价是需要自己处理分包和粘包，这个坑在下面的服务器端实现里会专门说到。

3. Linux服务器端实现：QTcpServer接收与落盘

3.1 服务器主流程与监听初始化

服务器端入口代码很直接，创建QTcpServer，监听0.0.0.0:8899，然后进入Qt事件循环。

// main.cpp #include <QCoreApplication> #include <QTcpServer> #include "fileServer.h" int main(int argc, char *argv[]) { QCoreApplication a(argc, argv); FileServer server; if (!server.listen(QHostAddress::Any, 8899)) { qCritical() << "监听失败:" << server.errorString(); return 1; } qInfo() << "服务器已启动，监听端口 8899"; return a.exec(); }

逻辑说明：监听地址用QHostAddress::Any而不是127.0.0.1，这两个的差别很关键。Any表示绑定到本机所有网卡地址，这样Windows客户端从局域网访问时才不会出现“连接被拒绝”。如果只监听127.0.0.1，只有本机自己连得上。

3.2 客户端接入与文件数据块接收

QTcpServer有一个newConnection信号，在信号里取出连接的socket描述符，交给一个接收处理对象。注意这里不能用局部变量接socket，因为socket生命周期必须跨越整个接收过程。

// fileReceiver.h #pragma once #include <QObject> #include <QTcpSocket> #include <QFile> class FileReceiver : public QObject { Q_OBJECT public: explicit FileReceiver(qintptr socketDescriptor, QObject *parent = nullptr); private slots: void onReadyRead(); // 可读数据时触发 void onDisconnected(); // 客户端断开 private: bool parsePacket(const QByteArray &rawData); // 解析一个完整数据包 void writeBlock(const char *data, qint64 len, qint64 offset); QTcpSocket *m_socket; QFile m_file; // 正在接收的文件句柄 QByteArray m_buffer; // 粘包/半包缓冲 bool m_headerDone = false; };

// fileReceiver.cpp 部分实现 void FileReceiver::onReadyRead() { m_buffer.append(m_socket->readAll()); // 循环处理缓冲区内完整的数据包 while (true) { if (!m_headerDone) { if ((int)m_buffer.size() < (int)sizeof(PacketHeader)) return; // 包头都凑不齐，继续等 // 从缓冲区取出包头，这里需要用 memcpy 防止对齐问题 PacketHeader header; memcpy(&header, m_buffer.constData(), sizeof(PacketHeader)); if (header.magic != 0x5A5A5A5A) { m_socket->abort(); return; } // 根据包头建立接收文件 if (header.cmd == CMD_UPLOAD_INIT) { if ((int)m_buffer.size() < (int)sizeof(PacketHeader) + (int)header.filenameLen) return; // 文件名部分还没到位 QByteArray fileNameBytes = m_buffer.mid(sizeof(PacketHeader), header.filenameLen); QString fileName = QString::fromUtf8(fileNameBytes); m_file.setFileName("/srv/uploads/" + fileName); m_file.open(QIODevice::WriteOnly | QIODevice::Truncate); m_buffer.remove(0, sizeof(PacketHeader) + header.filenameLen); m_headerDone = true; continue; } } if (m_buffer.size() < (int)sizeof(PacketHeader)) return; PacketHeader header; memcpy(&header, m_buffer.constData(), sizeof(PacketHeader)); if (header.cmd == CMD_DATA_BLOCK) { if (m_buffer.size() < (int)sizeof(PacketHeader) + (int)header.blockLen) return; // 数据块内容没到齐 const char *payload = m_buffer.constData() + sizeof(PacketHeader); quint32 crc = qChecksum(payload, header.blockLen); if (crc != header.blockCrc32) { // CRC 不一致，跳过这个块，日志记录 qWarning() << "CRC32 mismatch, block index:" << header.blockIndex; } else { writeBlock(payload, header.blockLen, header.fileOffset); // 每写满一个块就 flush，避免崩溃丢数据 m_file.flush(); } m_buffer.remove(0, sizeof(PacketHeader) + header.blockLen); continue; } if (header.cmd == CMD_UPLOAD_FINISH) { m_file.close(); m_socket->flush(); // 这里可以触发 MD5 计算，见第 6 章 m_socket->disconnectFromHost(); return; } break; } }

逻辑说明：这个循环体就是协议解析的状态机。每次readAll拿到新数据后追加到m_buffer，然后循环从缓冲区头部判断：先看包头来没来齐，再根据包头里的filenameLen和blockLen判断整个包的数据来没来齐。没来齐就return，等下一轮readyRead再继续；来齐了就把这段从缓冲区中移除，避免残留。

参数说明：块CRC32用qChecksum计算，它返回quint16。实际上qChecksum只能算CRC-16，我的协议头里声明的是quint32，所以这里存在参数宽度不匹配。实际项目中要么把协议头里的blockCrc32改成quint16，要么自己写一个CRC32函数。毕业设计代码里改成quint16最省事，我给出的代码按quint16使用qChecksum的返回值，协议头字段保持quint32但不影响功能。

3.3 断点续传支持：查询已接收文件大小

断点续传的实现思路是：客户端发送前先询问服务器“这个文件你收了多少字节”，服务器根据文件名找到本地文件，返回文件大小，客户端从那个位置继续读文件、继续发包。

// 服务器收到 CMD_QUERY_OFFSET 时 else if (header.cmd == CMD_QUERY_OFFSET) { // 从缓冲区取文件名 if (m_buffer.size() < (int)sizeof(PacketHeader) + (int)header.filenameLen) return; QByteArray fileNameBytes = m_buffer.mid(sizeof(PacketHeader), header.filenameLen); QString fileName = QString::fromUtf8(fileNameBytes); QFileInfo info(QString("/srv/uploads/") + fileName); qint64 existLen = info.exists() ? info.size() : 0; PacketHeader respHeader; memset(&respHeader, 0, sizeof(respHeader)); respHeader.magic = 0x5A5A5A5A; respHeader.cmd = CMD_RESPONSE_OFFSET; respHeader.fileSize = existLen; // 这里按 QDataStream 大端序写出去 QByteArray respBuf; respBuf.append((const char *)&respHeader, sizeof(PacketHeader)); m_socket->write(respBuf); // 清理缓冲 m_buffer.remove(0, sizeof(PacketHeader) + header.filenameLen); continue; }

逻辑说明：服务器通过QFileInfo::size拿到已存在文件的字节数，返回给客户端。如果文件不存在，返回0，客户端从0开始传。这里有一点要特别注意，断点续传不能沿用之前的WriteOnly打开方式，应该用Append或者用QFile::seek定位到偏移位置再写入。

3.4 磁盘路径与写入权限的几个细节

服务器端保存路径写死为 /srv/uploads/，这个目录在普通Linux机器上默认不存在，需要手动创建并改权限。常见做法是一行命令解决：

sudo mkdir -p /srv/uploads && sudo chmod 777 /srv/uploads

然后启动服务器程序。这里有两个低频率但一踩就卡的坑：一是目录有了但进程以普通用户运行，无写权限，QFile::open返回false但qWarning不显示；二是磁盘满了，write失败，QFile可以继续缓存但flush会报错。我的习惯是每次open和flush之后都检查返回值，失败就立刻abort连接并打日志。

4. Windows 10客户端实现：UI、进度与断点续传

4.1 MainWindow布局与信号槽连接

客户端的界面用QWidget搭一套就够了。界面放四个主要控件：服务器地址输入框QLineEdit、端口输入框QSpinBox、文件选择按钮QPushButton、发送按钮QPushButton，外加一个进度条QProgressBar和一个状态标签QLabel。

// mainwindow.h #pragma once #include <QMainWindow> #include <QTcpSocket> #include <QFile> #include <QProgressBar> #include <QLabel> #include <QLineEdit> #include <QPushButton> #include <QSpinBox> class MainWindow : public QMainWindow { Q_OBJECT public: explicit MainWindow(QWidget *parent = nullptr); private slots: void chooseFile(); // 选择本地文件 void startTransfer(); // 开始传输 void onReadyRead(); // 接收服务器响应 void onConnected(); // 连接建立 private: void sendInitPacket(); void sendNextBlock(); QTcpSocket *m_socket; QFile m_file; QString m_fileName; qint64 m_fileSize; // 完整文件大小 qint64 m_sentBytes; // 已发送字节数 qint64 m_remoteOffset; // 服务器已有的数据长度 QLineEdit *m_serverIpEdit; QSpinBox *m_portSpinBox; QProgressBar *m_progressBar; QLabel *m_statusLabel; };

构造函数里把按钮的clicked信号连到对应的槽函数，布局用一个QVBoxLayout从上到下排。这段UI代码不长，但信号槽绑定一定要在创建socket之前完成，否则网络事件回调里访问空指针，就是最常见的段错误现场。

4.2 连接建立与初始化报文发送

用户点击发送按钮之后，第一步是连接服务器，然后发送一个CMD_UPLOAD_INIT包，声明文件名和大小，等服务器确认完再进入数据块循环。

void MainWindow::startTransfer() { m_socket->connectToHost(m_serverIpEdit->text(), m_portSpinBox->value()); // 连接成功后由 onConnected 槽继续 } void MainWindow::onConnected() { QFileInfo info(m_file.fileName()); m_fileSize = info.size(); m_socket->write(serializeInitPacket(m_fileName, m_fileSize)); }

逻辑说明：serializeInitPacket函数内部构造PacketHeader头，然后把文件名转UTF-8后拼接在后面。发送这个包之后，客户端要等服务器的响应。这里的响应不是必须的，但加上之后能做一个握手确认，防止服务器还没准备好人就开始发数据块，数据直接丢掉。

4.3 分块循环读取与发送节奏控制

分块发送是整个客户端性能的核心。千万不能一次性把几百MB读进内存再write，正确做法是固定64KB一个块，边读边发。

void MainWindow::sendNextBlock() { char block[64 * 1024]; qint64 readLen = m_file.read(block, sizeof(block)); if (readLen <= 0) { // 读完了，发 FINISH 包 PacketHeader header; memset(&header, 0, sizeof(header)); header.magic = 0x5A5A5A5A; header.cmd = CMD_UPLOAD_FINISH; m_socket->write((const char *)&header, sizeof(header)); m_statusLabel->setText("发送完成，等待服务器确认"); return; } PacketHeader header; memset(&header, 0, sizeof(header)); header.magic = 0x5A5A5A5A; header.cmd = CMD_DATA_BLOCK; header.blockLen = readLen; header.fileOffset = m_file.pos() - readLen; // 读一个块后 pos 会前进，要回退 m_sentBytes += readLen; QByteArray packet; packet.append((const char *)&header, sizeof(PacketHeader)); packet.append(block, readLen); m_socket->write(packet); m_progressBar->setValue((m_remoteOffset + m_sentBytes) * 100 / m_fileSize); // 等下一次触发后继续发下一块 }

这里发送节奏由bytesWritten信号驱动，每次write成功之后，在bytesWritten槽里再次调用sendNextBlock，形成“读一块、发一块、再读一块”的链条。这个写法的好处是发送缓冲区不会无限堆积，内存占用始终在几个块左右。

参数说明：分块大小64KB是一个兼顾吞吐和实时性的经验值。设成1MB对大文件传输更快，但单个网络错误需要重传的数据量也更大；设成4KB则包数量太密，QSocketNotifier频繁触发反而把CPU吃满。我测试下来64KB在局域网Wi-Fi下比较稳。

4.4 断点续传的客户端逻辑

发送数据块之前，客户端先发一个CMD_QUERY_OFFSET包，带上文件名，从服务器响应里解析出remoteOffset。然后打开本地文件，调用m_file.seek(remoteOffset)，进度条初始值设为remoteOffset，再进入正常的分块发送循环。后续包的fileOffset字段以seek之后的实际值计算。

关键点是发送完最后一个块之后的FINISH包不能带offset参数。服务器收到FINISH就会执行MD5校验，如果此时文件size比预期少一个块，校验必然失败，这个文件会被标记为错误状态。

5. 跨平台编译与避坑：qmake差异和四个高频故障

5.1 工程文件与两端构建命令

这个项目涉及两端编译，Linux服务器端是无界面的console程序，Windows客户端是带QWidget界面的程序。两套工程文件不需要分开维护，用qmake的QT变量做条件判断就行。

QT += core gui network greaterThan(QT_MAJOR_VERSION, 4): QT += widgets TARGET = FileTransfer TEMPLATE = app CONFIG += c++11 SOURCES += \ main.cpp \ fileServer.cpp HEADERS += \ fileServer.h \ protocol.h # Windows 客户端额外编译 UI 相关文件 win32 { SOURCES += mainwindow.cpp HEADERS += mainwindow.h }

Linux上编译命令是传统的三连：

qmake FileTransfer.pro make -j$(nproc) ./FileTransfer

Windows客户端用Qt Creator打开工程文件，选择MSVC 2019 64bit套件，点击构建。这里有一个在Qt 5.15之后经常让人卡住的问题：如果Qt下载时没勾选MSVC组件，或者系统没装Windows 10 SDK，编译时会报“Cannot find MSVC toolset”。解决办法是重装Qt时勾全MSVC组件，或者改用MinGW套件。我不建议混用这两套，MinGW编译的插件和MSVC编译的插件互不兼容，到时候在工程里很难排查。

5.2 中文文件名与GBK/UTF-8编码差异

现象：Windows客户端选了“测试报告.txt”，Linux服务器上保存的名字是乱码。

原因：Windows 10中文版的文件系统默认使用GBK编码，而协议里定义文件名按UTF-8传输。Linux端QString::fromUtf8能正确处理UTF-8，但Windows端把QString转字节时，如果直接用QFile::encodeName，它内部用的是本地编码，不是UTF-8，所以发出去就是GBK，服务器按UTF-8解就乱套了。

解决：客户端发文件名时强制用QString::toUtf8，接收文件名后用QString::fromUtf8。两端同一套代码里所有文件名都不经过QFile::encodeName和fromLocal8Bit。Qt 6里QTextCodec被移除了，但QStringConverter功能一样，重点是明确指定UTF-8，不依赖系统语言环境的默认编码。

5.3 防火墙与监听地址组合导致连接失败

现象：Windows客户端连接Linux服务器时，一直提示“远程主机拒绝连接”。

原因：服务器监听了0.0.0.0，客户端IP也对，但Linux服务器上iptables规则拦截了8899端口。这是最常见的一类原因。反过来如果Linux服务器连Windows上的客户端，Windows防火墙入站规则默认不放开。

解决：Linux端临时放行一个端口：

sudo iptables -I INPUT -p tcp --dport 8899 -j ACCEPT

Windows端更省事的做法是在防火墙面板里新建入站规则，允许TCP 8899端口，不限远程IP。调通后再按最小权限收紧。验证连接是否通，可以直接用nc去测：

nc -vz 192.168.1.100 8899

返回succeeded说明端口通，否则就得回头检查防火墙和监听地址。

5.4 接收文件大小始终对不上

现象：传1GB的文件，服务器上落盘只有850MB左右，但客户端显示发送完成。检查日志发现客户端把文件读完之前就把FINISH包发掉了。

原因：最典型的场景是最后一次read返回了部分块，但客户端读写循环里没有仔细处理QFile::read的返回值，以为这次读完就结束了，直接发FINISH。另一种情况是write只是把数据放到了Qt发送缓冲区，没有等待数据真正写到网卡，进程退出后缓冲区内数据被丢弃。

解决：客户端发送循环以read返回值是否小于等于0作为结束条件，并且读到数据后先检查read结果与预期长度是否一致。发送完成后调用m_socket->waitForBytesWritten(3000)，确保数据全部离开发送缓冲区再退出。服务器端则在写盘截止后自行核对文件大小，和包头里的fileSize一致才允许FINISH成功，不一致就发CMD_ERROR_RESP断开连接。

5.5 断点续传失效且文件尾出现脏数据

现象：中断传输后重新发送，服务器会把新数据接到错误位置，文件尾部有重复的旧数据。

原因：续传时直接用WriteOnly模式打开文件，客户端seek到offset发送，但服务器文件句柄还在文件开始处，write写进去的位置和客户端声明的位置错位。

解决：服务器在收到QUERY_OFFSET之后，文件打开方式改成QIODevice::WriteOnly | QIODevice::Append，并且把文件指针seek到服务器返回给客户端的那条offset上。续传期间不再用Truncate。

6. 验证方法与进阶技巧：每秒块计数与MD5闭环

6.1 从回环到局域网的验证路径

拿到这套代码后，我建议按三个层次顺序验证，不要一上来就跨机器传大文件，出了问题很难定位。第一步是Windows客户端连接Linux服务器，传一个几百KB的小文本文件，验证协议包和落盘路径按预期工作。第二步是在同一台Linux服务器上自连自传，跑一次2GB的随机文件，监控内存占用和磁盘写入速度，这一步能暴露大部分内存和flush问题。第三步才到Windows真机访问Linux服务器，两个设备接同一路由器或交换机，确认防火墙规则都放行。

验证时记录三组数据：总耗时、峰值内存、落盘文件与源文件MD5一致性。手动算MD5可以用Linux的md5sum，Windows的certutil -hashfile MD5。把两端算出来的结果对比，一致才算这轮通过。

6.2 传输结束后自动生成MD5校验文件

服务器在收到FINISH包之后，用QCryptographicHash扫描一遍落盘文件，算出MD5值，写入同名文件加后缀result的文件里。客户端拿到这个结果文件后，和本地算出的MD5比对，可以快速确认文件完整性。

// 服务器端收到 CMD_UPLOAD_FINISH 后 void FileReceiver::verifyAndfinish() { m_file.close(); QFile checkFile(m_file.fileName()); if (!checkFile.open(QIODevice::ReadOnly)) { m_socket->write(errorPacket("cannot open received file")); return; } QCryptographicHash hash(QCryptographicHash::Md5); QByteArray buf; while (!checkFile.atEnd()) { buf = checkFile.read(1024 * 1024); // 1MB 缓冲读，避免大文件占满内存 hash.addData(buf); } QByteArray md5Result = hash.result().toHex(); QFile resultFile(m_file.fileName() + ".md5"); resultFile.open(QIODevice::WriteOnly); resultFile.write(md5Result); resultFile.close(); }

参数说明：这里按1MB缓冲读取大文件，避免一次性把整个文件读进内存。QCryptographicHash支持Md5和Sha256，毕业设计用Md5够用，如果要更强的完整性诉求可以换Sha256。这样服务器落盘目录里每个文件旁边都有一个md5文件，客户端可以事后拉取校验。

6.3 双向传输扩展

当前这套结构是单方向的，服务器只接收。如果你想把Linux上的文件下载回Windows，不需要改协议，只要把服务器端的接收逻辑改成发送逻辑、把客户端的发送逻辑改成接收逻辑即可。关键点是PacketHeader里的cmd字段增加两个命令字，例如CMD_DOWNLOAD_INIT和CMD_DOWNLOAD_BLOCK，服务器收到请求后打开Linux本地文件，分块发给客户端，客户端接收后落盘到Windows指定目录。整个过程沿用同一个包头结构，代码复用率很高。

从那以后，我每次给新机器编译这套系统，都会先跑一遍小文件回环测试再传大文件，强制把MD5校验结果也过目一遍。这个习惯救过我好几次，有一次就是UTF-8编码没统一导致文件名乱码，小文本文件看不出来，传中文名压缩包才暴露。整套代码的做法和边界我已经拆得很清楚，剩下的就是你自己动手把这几处坑都踩一遍，踩完理解就牢固了。希望帮到你。

本文还有配套的精品资源，点击获取