简介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这里我把两种方案的对比整理一下方便你根据自己手头项目的情况做选择。对比项QNetworkAccessManagerQFtp模块libcurlQt官方支持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上传Demo3.1 环境准备与工程配置我用的是Qt 5.15.2MSVC2019 64位在Windows 10环境开发FTP服务器这边用一个本地搭建的FileZilla Server做联调。你如果是别的环境操作大同小异。工程里面不需要额外加模块默认的core、gui、network就够了。如果你要打印调试日志把network模块加进去之后在pro文件里写上QT core gui network greaterThan(QT_MAJOR_VERSION, 4): QT widgets CONFIG c11 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_castQNetworkReply *(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的引入与使用如果你的项目偏偏是Qt6QNetworkAccessManager已经不带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”项目跑在Qt6QNetworkAccessManager不再支持ftp换QFtp或libcurl能登录能列目录一上传就超时FTP数据连接被封或服务器要求主动模式检查防火墙服务端开启被动模式并放行数据端口中文文件名上传后乱码服务器使用GBKQt内默认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的队列上传、以及一个模拟失败重试的按钮。后面接入真实业务时直接对照着改动参数就能跑省了重新查文档的功夫。如果你也要长期维护类似的上传功能非常建议按这个“一主两备”的结构去留代码。项目源码本身不复杂但把网络超时、文件生命周期、编码转换这些细节处理好才算是一个能在生产环境里站得住脚的上传模块。希望这篇梳理能帮你少踩几个坑。本文还有配套的精品资源点击获取 Qt FTP上传：QNetworkAccessManager与QFtp对比
简介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这里我把两种方案的对比整理一下方便你根据自己手头项目的情况做选择。对比项QNetworkAccessManagerQFtp模块libcurlQt官方支持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上传Demo3.1 环境准备与工程配置我用的是Qt 5.15.2MSVC2019 64位在Windows 10环境开发FTP服务器这边用一个本地搭建的FileZilla Server做联调。你如果是别的环境操作大同小异。工程里面不需要额外加模块默认的core、gui、network就够了。如果你要打印调试日志把network模块加进去之后在pro文件里写上QT core gui network greaterThan(QT_MAJOR_VERSION, 4): QT widgets CONFIG c11 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_castQNetworkReply *(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的引入与使用如果你的项目偏偏是Qt6QNetworkAccessManager已经不带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”项目跑在Qt6QNetworkAccessManager不再支持ftp换QFtp或libcurl能登录能列目录一上传就超时FTP数据连接被封或服务器要求主动模式检查防火墙服务端开启被动模式并放行数据端口中文文件名上传后乱码服务器使用GBKQt内默认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的队列上传、以及一个模拟失败重试的按钮。后面接入真实业务时直接对照着改动参数就能跑省了重新查文档的功夫。如果你也要长期维护类似的上传功能非常建议按这个“一主两备”的结构去留代码。项目源码本身不复杂但把网络超时、文件生命周期、编码转换这些细节处理好才算是一个能在生产环境里站得住脚的上传模块。希望这篇梳理能帮你少踩几个坑。本文还有配套的精品资源点击获取