简介：Qt开发者可参考的一份FTP上传Demo，使用QNetworkAccessManager实现文件上传，解决在Qt应用中直接与FTP服务器交互的需求。资源面向具备基础Qt编程经验的开发者，聚焦FTP上传的完整实现，便于快速集成或二次扩展。压缩包共13个文件，包含4个C++源文件、3个头文件和2个UI界面文件，另有工程配置文件和翻译文件，整体仅47KB，结构紧凑；其中C++源文件实现上传逻辑与界面控制，头文件提供类声明，UI文件对应设计界面，便于对照阅读。目前已有446人学习下载，适合作为Qt网络编程的入门示例。Demo展示了从打开本地文件、构造QNetworkRequest请求、设置Content-Type头、调用put()上传，到通过finished与uploadProgress信号处理上传结束与进度更新的完整链路；界面代码与核心逻辑分离，读者可快速定位上传功能对应实现，也可在此基础上扩展多文件上传、错误处理等实际功能。 很多人以为Qt做网络通信，无非就是HTTP接口调一调、JSON收一收，真正要跟服务器交换文件时才发现，FTP协议依然是不少内网环境、嵌入式设备、老系统之间传输文件的主力。前几天我这边有个小需求，要把设备端生成的报表定时传到内网FTP服务器，顺手搭了一个完整的Qt FTP上传Demo，今天把整个思路和踩坑过程整理出来。如果你正准备在自己的Qt项目里接入FTP上传，又不想看到一堆云里雾里的文档，这篇文章应该能让你少走很多弯路。
这个Demo的核心内容是基于Qt的网络模块实现文件上传，覆盖了登录、上传、进度回调、错误处理几个完整环节，同时也聊一聊Qt5环境和Qt6环境下的方案差异。适合刚接触Qt网络编程、或者需要在桌面端实现文件上报功能的开发者参考。
1. 为什么写这个Demo：场景与需求梳理
1.1 这个Demo解决什么问题
先说需求场景：一台Windows工控机，每隔一段时间会把本地生成的数据文件上传到局域网里的FTP服务器。这个服务器可能是NAS、Windows自带的IIS FTP，也可能是Linux上跑的vsftpd。文件不大，数量不多，但要求稳定、可控，能实时看到上传进度，失败时还要能自动重试。
Qt做这件事的优势很明显：跨平台、自带网络库、信号槽天然适合异步操作，不需要额外引入libcurl这类依赖。实际上很多Qt开发者一听到“FTP上传”，第一反应是去翻文档找QFtp类，但这里有个坑：QFtp并不是Qt官方标准库的一部分，它属于Qt FTP模块，早期以单独组件形式存在，后来长期没人维护。Qt5里你还能从源码编译出来用，到了Qt6基本就被官方放弃维护了。
所以在2024年之后的实际操作里，我更推荐优先考虑QNetworkAccessManager。它在Qt5时代就已经支持ftp协议，写法和HTTP请求几乎一样，API稳定，文档齐全。如果你的项目正好是Qt5.15 LTS，用这个方法最快。只有当你必须跑在Qt6上、又不方便自己编译QFtp时，才需要额外下载第三方编译好的QFtp模块，或者考虑用libcurl方案。
1.2 技术选型的纠结：QFtp还是QNetworkAccessManager
这里我把两种方案的对比整理一下，方便你根据自己手头项目的情况做选择。
| 对比项 | QNetworkAccessManager | QFtp模块 | libcurl |
|---|---|---|---|
| Qt官方支持 | Qt5支持，Qt6移除了ftp支持 | 非官方核心模块，长期不维护 | 第三方库，需要额外集成 |
| API复杂度 | 低，put/post类似HTTP | 中等，命令队列机制 | 较高，回调较底层 |
| 主动上传进度 | 支持uploadProgress信号 | 支持commandFinished等 | 需用CURLOPT_XFERINFO |
| 断点续传能力 | 较弱，需自己实现 | 支持，有专用命令 | 强，可精确控制 |
| 中文文件名支持 | 需要自行处理编码 | 需要设置编码 | 与设置相关 |
| 跨平台表现 | 稳定 | 依赖模块编译环境 | 稳定 |
我的结论是：如果你现在用的是Qt 5.15，别犹豫，直接QNetworkAccessManager，一条put请求就能干活，代码量最少；如果项目锁定Qt6，要么去拉一份第三方编译好的QFtp源码包，要么直接用libcurl，具体情况我在后面第4节补充方案。
2. FTP上传的核心原理与Qt设计思路
2.1 FTP协议里你必须知道的几个点
FTP协议沿用太久了，很多新人对它的印象停留在“输入账号密码就能传文件”，但真要自己写代码时，有几个细节直接决定你调通调不通。
FTP有两种连接模式：主动模式（PORT）和被动模式（PASV）。主动模式下，服务器主动往客户端的端口发连接，很多客户端处于NAT之后，主动模式根本通不了；被动模式下，客户端主动连接服务器开放的数据端口，能穿透大部分防火墙。Qt的QNetworkAccessManager内部默认走被动模式，实际用起来基本不需要关心，但你要有这个概念——万一你们单位FTP服务器设置了“仅允许主动模式”或者某些奇怪的安全策略，那就是连不上、上传超时的元凶之一，后面排查时优先看一眼。
第二个关键点是数据连接与命令连接的分离。FTP用21端口发命令，用另一个数据端口传文件。Qt把这层封装得很好，但我们自己定位问题时要知道，如果数据端口被封，表现往往是“能登录、列目录正常，但一传文件就卡死超时”。
第三个是编码问题。很多中文Windows环境里的FTP服务器，默认用的是GBK编码，而Qt内部统一是UTF-8。如果你直接拿中文文件名去put，服务器那边看到的可能是一串乱码，甚至直接报错。这个在第5节里会给具体处理方案。
2.2 Qt网络模块的工作机制与信号槽设计
QNetworkAccessManager做FTP上传的思路，本质上和HTTP上传没有区别：构造QUrl，组装成QNetworkRequest，调用put()方法，然后通过信号槽感知结果。
关键槽函数有四个：uploadProgress信号实时返回已上传字节数和总字节数；finished信号代表请求结束，用reply->error()判断成功与否；reply->errorOccurred可以捕获错误对象；遇到重定向或认证过期时，还可以用authenticationRequired信号去处理。
编写Qt网络代码时，我建议一定要用异步套路，绝不在UI线程里搞阻塞式等待。哪怕文件只有几百KB，一旦网络抖动，阻塞几秒钟，界面就卡死，用户体验极差。这个Demo的核心逻辑也全部建立在信号槽异步回调上，上传过程里界面照常刷新，用户还能随时取消。
3. 完整实现：Qt5 QNetworkAccessManager上传Demo
3.1 环境准备与工程配置
我用的是Qt 5.15.2（MSVC2019 64位），在Windows 10环境开发，FTP服务器这边用一个本地搭建的FileZilla Server做联调。你如果是别的环境，操作大同小异。
工程里面不需要额外加模块，默认的core、gui、network就够了。如果你要打印调试日志，把network模块加进去之后，在pro文件里写上：
QT += core gui network greaterThan(QT_MAJOR_VERSION, 4): QT += widgets CONFIG += c++11 TARGET = FtpUploadDemo TEMPLATE = app SOURCES += main.cpp MainWindow.cpp HEADERS += MainWindow.h FORMS += MainWindow.ui这里面有个经常被忽略的点：如果你在MainWindow里直接引入头文件，一定记得构造函数里new一个QNetworkAccessManager对象时要传this作为父对象，否则万一一不小心忘了释放，轻则内存泄漏，重则程序退出时崩溃。
3.2 上传核心代码实现
我先贴一个最精简但可直接跑通的上传函数。核心逻辑用QNetworkAccessManager::put()完成，只传文件内容，不经过本地临时文件。
void MainWindow::startUpload(const QString &localPath, const QString &remoteUrl) { QFile *file = new QFile(localPath, this); if (!file->open(QIODevice::ReadOnly)) { qWarning() << "打开文件失败: " << file->errorString(); return; } QUrl url(remoteUrl); url.setUserName("ftpuser"); url.setPassword("ftpPass123"); QNetworkRequest request(url); request.setTransferTimeout(15000); QNetworkReply *reply = m_manager->put(request, file); connect(reply, &QNetworkReply::uploadProgress, this, &MainWindow::onUploadProgress); connect(reply, &QNetworkReply::finished, this, &MainWindow::onUploadFinished); // 这里记录reply，方便中途取消 m_currentReply = reply; m_currentFile = file; }这里有几个细节说明一下：
- put()的第二个参数可以直接传QIODevice指针，它内部会异步读取文件内容，并不需要你先手动readAll()把数据塞进内存。大文件场景下readAll()会直接撑爆内存，这个写法才是安全姿势。
- QNetworkRequest的setTransferTimeout是Qt 5.15新增的接口，单位是毫秒，可以设置整个请求的超时时间。很多老项目遇到上传卡死，就是因为没设置超时，服务器无响应时客户端永远等在那里。
- url里直接带用户名密码是偷懒写法。更规范的做法是用AuthenticationRequired信号动态提供认证信息，但Demo阶段图省事，直接放在URL里完全没问题。
3.3 关键参数与进度计算
进度回调我单独写了个槽函数，实现并不复杂，核心是如何从uploadProgress信号里拿到完整信息。
void MainWindow::onUploadProgress(qint64 bytesSent, qint64 bytesTotal) { if (bytesTotal <= 0) return; // 部分服务器不返回总大小，直接忽略 int percent = qRound(bytesSent * 100.0 / bytesTotal); ui->progressBar->setValue(percent); ui->labelInfo->setText(QString("已上传: %1 / %2 (%3%)") .arg(bytesSent) .arg(bytesTotal) .arg(percent)); }bytesTotal如果是-1或者0，说明服务器没有提供文件总大小，常见于某些简化版FTP服务端。这时候进度条会一直处于不确定状态，界面上就不要强行算百分比了，只显示已上传字节数即可。
另外，上传结束后一定要判断reply->error()，因为finished信号在出错时也会触发。如果直接以为“走finished就成功”，代码会在出错时静默失败，这个坑不少人都踩过。
void MainWindow::onUploadFinished() { QNetworkReply *reply = qobject_cast<QNetworkReply *>(sender()); if (!reply) return; if (reply->error() == QNetworkReply::NoError) { ui->labelInfo->setText("上传成功"); } else { ui->labelInfo->setText("上传失败: " + reply->errorString()); } reply->deleteLater(); if (m_currentFile) { m_currentFile->close(); m_currentFile->deleteLater(); m_currentFile = nullptr; } }这里有个重要的习惯：无论成功失败，reply必须调用deleteLater()释放，否则内存会被网络回复占着不还。还有，不要把m_currentFile直接delete，用deleteLater()更安全，避免在信号处理过程中对象半销毁导致崩溃。
4. 升级方案：QFtp与断点续传
4.1 QFtp的引入与使用
如果你的项目偏偏是Qt6，QNetworkAccessManager已经不带ftp协议了，这时就得考虑QFtp模块。QFtp虽然官方不维护，但至今仍然能通过源码编译在Qt6里使用。GitHub上还有爱好者维护的qtftp库，拉下来qmake编译即可。
QFtp的使用方式和QNetworkAccessManager不太一样，它采用命令队列机制：你发出的每个ftp指令都会进入队列，一个接一个执行。典型的流程是连接服务器、登录、切换目录、然后put，每个步骤都通过commandFinished信号来推进。
QFtp *ftp = new QFtp(this); connect(ftp, &QFtp::commandFinished, this, &MainWindow::onFtpCommandFinished); ftp->connectToHost("192.168.1.100", 21); ftp->login("ftpuser", "ftpPass123"); ftp->cd("/upload"); ftp->put(file, "report_20250101.dat");这里要注意的是，QFtp的put()在执行完命令后，并没有一个专门表示“全部完成”的信号，你需要在commandFinished里识别当前命令，当stateChanged回到QFtp::Unconnected时，说明整个传输结束。刚开始用QFtp的人十有八九会在这里迷糊。
4.2 断点续传与失败重试（简化）
QFtp的另一个优势是支持断点续传。思路很简单：上传开始前先发送size命令查询远端文件大小，如果远端文件已存在且大小小于本地文件，就把本地文件指针偏移到这个位置，再调用QFtp的resume()接口，让后续put从上次进度继续。
这个功能在QNetworkAccessManager里就比较难实现了，因为API层面没有暴露ftp底层控制指令。所以如果产品需求里明确写了“网络断了要能断点续传”，我劝你直接上QFtp或者libcurl，别在QNetworkAccessManager上硬刨坑。
至于失败重试，我的建议是做指数退避。第一次失败等1秒重试，第二次等2秒，第三次等4秒，最多重试5次左右。千万别做“失败立马重试”的死循环，容易把服务器打挂，也会让日志瞬间爆炸。
5. 常见问题与排查技巧实录
这段时间做这个Demo，联调时确实遇到过不少问题，挑几个代表性的整理成表，大家对照着排查会非常快。
| 现象 | 原因 | 解决思路 |
|---|---|---|
| 上传时报“Protocol not supported” | 项目跑在Qt6，QNetworkAccessManager不再支持ftp | 换QFtp或libcurl |
| 能登录能列目录，一上传就超时 | FTP数据连接被封，或服务器要求主动模式 | 检查防火墙；服务端开启被动模式并放行数据端口 |
| 中文文件名上传后乱码 | 服务器使用GBK，Qt内默认UTF-8 | 手动编解码，或url设置后用QTextCodec转换 |
| 上传完成但服务器文件大小为0 | 文件指针未定位到开头，或File未open成功 | 检查QFile是否还在开头位置，检查打开状态 |
| 进度条一直0%，最后直接完成 | 服务器不返回总大小，bytesTotal为-1 | 改为只显示已传字节数，不做百分比 |
| 程序退出时偶发崩溃 | reply或file对象释放时机不对 | 统一用deleteLater()，并断开信号连接 |
再补充一个比较隐蔽的点：QNetworkAccessManager的put()如果传的是QFile指针，这个QFile的生命周期必须由你自己管理。很多人写完代码没崩，只是因为文件小、传输快，还没来得及释放程序就退了。一旦文件传得慢，用户中途点了取消，QFile已经被回收，程序立刻崩给你看。我的习惯是始终用成员变量保存这个文件指针，并在finished或取消逻辑里统一清理。
还有个经验是，自定义FTP服务器联调时，优先看状态码。服务器返回的FTP状态码非常有规律，530是认证失败，550是文件不存在或权限不够，421是服务端超时断开。Qt在errorString()里通常会把FTP服务器返回的原文带出来，你看到类似“530 Login incorrect”这种信息，基本就能定位是账密问题还是目录权限问题，不需要瞎猜。
6. 实际操作中的几点体会
最后分享几个我实际用下来的体会。
一是能用现成API解决就别自己造轮子，但一定要知道轮子底下是怎么转的。QNetworkAccessManager虽然一行put就完事，但如果你不理解FTP的被动模式、数据连接、命令连接这些事，联调遇阻时依然会一头雾水。反过来，把这些基础弄明白，你再看QFtp的代码、甚至看libcurl的示例，都会顺畅很多。
二是超时设置一定不能省。最初我把setTransferTimeout注释掉，觉得内网稳如老狗，结果有一次服务器磁盘满了，FTP连接建立后迟迟没有响应，客户端就这么干等着。加上这个接口之后，至少能快速失败、触发重试逻辑，比无限等待可强多了。
三是在Demo里把所有逻辑写清楚、注释写完整，比什么都强。这个Demo我最后保留了三个入口：直接put上传、QFtp的队列上传、以及一个模拟失败重试的按钮。后面接入真实业务时，直接对照着改动参数就能跑，省了重新查文档的功夫。如果你也要长期维护类似的上传功能，非常建议按这个“一主两备”的结构去留代码。
项目源码本身不复杂，但把网络超时、文件生命周期、编码转换这些细节处理好，才算是一个能在生产环境里站得住脚的上传模块。希望这篇梳理能帮你少踩几个坑。
本文还有配套的精品资源，点击获取
