简介QFTP是一套基于FTP协议的跨平台客户端源码面向使用C/Qt开发文件传输功能的开发者以及希望理解FTP通信实现细节的学习者。它可用于在桌面应用、IDE插件或文件管理工具中集成上传、下载能力也适合作为网络编程与协议解析的参考实现。压缩包共4个文件由2个cpp源文件和2个h头文件组成整体约24KB体量轻便其中源文件承载连接管理、FTP命令收发与数据传输逻辑头文件则声明对外接口和URL信息处理结构便于按模块阅读与二次开发。该源码已在Linux和Windows平台完成测试涉及跨平台API适配与基本功能验证已有297人学习或浏览。读者可从中了解FTP连接建立、LIST/RETR/STOR等命令执行、响应与错误处理以及URL主机、端口、认证信息的解析方式并据此裁剪、扩展或嵌入自有项目获得可定制的FTP客户端基础。1. 为什么还要捡起 QFTP 源码给设备运维工具加一个日志回传功能的时候需求很朴素每天凌晨把产线工控机上的日志目录整个拉回来顺便把新固件推上去。设备端只开了 21 端口除了 FTP 没别的口子可用。翻到 Qt 才发现从 Qt 5 开始 QFtp 就不再随 QtNetwork 一起发布了官方把它拆成独立模块必须自己把源码编进工程。这份 QFTP 源码已经在 Linux/Windows 两个平台完成过测试qmake 工程直接能编这正是它最值钱的地方FTP 协议本身不复杂真正麻烦的是跨平台里那一堆连接状态、被动模式报文解析和字节编码细节有人替你趟过一遍能省掉大半天。它适合手里已经有 Qt 工程、又必须跟老式 FTP 服务端打交道的人当成内部插件模块引进来的那种用法。2. 源码骨架与接入方式qtftp 模块怎么塞进现有 Qt 工程2.1 目录与文件职责拿到源码先别急着编先把文件职责摸清楚。QFtp 这一套东西不大核心就几个文件真正干活的都在qftp.cpp里。它没有第三方依赖只吃 QtCore 和 QtNetwork所以接进任何 Qt 工程都不会引入版本冲突这也是我一般优先选它的原因。文件职责改动频率qftp.h对外接口QFtp类声明、Command/State/TransferType枚举几乎不改qftp.cpp协议实现命令队列、控制连接、PASV/PORT 数据连接、响应解析改编码、加 TLS 时才动qftp_p.h私有实现QFtpPrivate持有 socket 和命令队列加字段时动qurlinfo.h/.cppQUrlInfo封装LIST返回的单条目录项基本不动qtftp.pro/CMakeLists.txt模块自身的构建脚本按需理解这张表的关键在于QFtp是纯异步的所有成员函数connectToHost、login、put都是「把命令塞进队列然后立刻返回一个整数 id」真正发字节是在事件循环里做的。这是后面所有调试思路的基础别把它当成阻塞式 API 用。2.2 qmake 子工程接入最省事的办法是把整个源码目录丢进工程的3rdparty/然后让.pro直接引用。不要试图装到系统 Qt 目录里那样换个开发机就得重来一遍血泪经验。QT core network # 源码放在工程内的 3rdparty/qtftp跟着仓库一起走 INCLUDEPATH $$PWD/3rdparty/qtftp/src/qftp DEPENDPATH $$PWD/3rdparty/qtftp/src/qftp HEADERS $$PWD/3rdparty/qtftp/src/qftp/qftp.h \ $$PWD/3rdparty/qtftp/src/qftp/qurlinfo.h SOURCES $$PWD/3rdparty/qtftp/src/qftp/qftp.cpp \ $$PWD/3rdparty/qtftp/src/qftp/qurlinfo.cppINCLUDEPATH让#include QFtp或#include qftp.h能定位到头文件DEPENDPATH是给 qmake 生成依赖关系用的漏了它改头文件不会触发重编。QT network不能少qftp.cpp里用到QTcpSocket、QHostAddress、QUrlInfo这些类。如果qftp_p.h在private/子目录下记得把那个路径也加进INCLUDEPATH否则编译时会报找不到私有头。2.3 CMake 接入与静态库导出新工程基本都用 CMake 了做法是把 qtftp 编成一个静态库业务代码只链这个 target头文件路径通过PUBLIC自动传递出去。add_library(qtftp STATIC ${CMAKE_CURRENT_SOURCE_DIR}/src/qftp/qftp.cpp ${CMAKE_CURRENT_SOURCE_DIR}/src/qftp/qurlinfo.cpp ) # PUBLIC谁链 qtftp谁就自动拿到这两个头文件搜索路径 target_include_directories(qtftp PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/src/qftp ${CMAKE_CURRENT_SOURCE_DIR}/src/qftp/private ) target_link_libraries(qtftp PUBLIC Qt5::Core Qt5::Network) # Linux 下要被主程序动态链接时必须开 PICWindows 无所谓 set_target_properties(qtftp PROPERTIES POSITION_INDEPENDENT_CODE ON)POSITION_INDEPENDENT_CODE ON这一行在 Linux 上是必须的忘了它主程序一旦是共享库或者开了-fPIC链接阶段就会甩出一堆 relocation 错误看着像玄学其实就这一个开关。业务侧只需要target_link_libraries(your_app PRIVATE qtftp)其余不用管。2.4 平台差异Linux 与 Windows 上要额外关注的三个点第一是头文件包含大小写。Linux 文件系统区分大小写代码里写#include QFtp在 Windows 上能过、到 Linux 直接翻车统一写成小写的qftp.h最稳。第二是文件路径分隔符QFtp::put的远端文件名参数必须用/本地路径交给QFile处理别自己拼字符串。第三是网络行为Linux 下默认的被动模式一般畅通Windows 上如果开发机装了安全软件被动模式的随机高端口有可能被拦表现是控制连接正常、数据连接永远挂住这一点在第 5 章会展开。3. 核心链路拆解一条 put 命令从入队到数据连接关闭3.1 QFtpPrivate 的命令队列与状态机qftp.cpp的主干是一个命令队列加一个状态机。QFtpPrivate内部维护QListCommand每条Command记录命令类型ConnectToHost、Login、Put、Get、List……、参数和返回给调用方的 id。QFtp的每个公开函数实际只做三件事构造 Command、addCommand入队、返回 id。// 简化后的主干展示命令入队的思路 int QFtp::put(QIODevice *dev, const QString file, TransferType type) { Q_D(QFtp); if (!dev) return -1; return d-addCommand(Put, file, dev); // 返回自增 id调用方拿它对齐信号 } int QFtpPrivate::addCommand(Command::Type type, const QString arg, QIODevice *dev) { Command cmd; cmd.type type; cmd.id nextId; // 全局自增commandStarted/commandFinished 靠它配对 cmd.arg arg; cmd.dev dev; pending.append(cmd); if (state Unconnected || state Idle) startNextCommand(); // 空闲就立刻发忙就排队等 done() return cmd.id; }这里的id是整个异步模型的锚点。你发出去五条命令commandStarted(id)和commandFinished(id, error)会按 id 一一回调业务层要靠 id 判断「刚才失败的那条到底是登录还是上传」。state用来防止并发Running状态下新命令只入队不发送startNextCommand在每收到226/250响应后才推下一条。理解了这一层就不会出现「连着调三次connectToHost结果状态乱套」的翻车现场。3.2 握手阶段connectToHost、login、cd 的时序因为命令是排队的连着写三行不需要嵌套回调这是 QFtp 用起来最舒服的地方class FtpClient : public QObject { Q_OBJECT public: explicit FtpClient(QObject *parent nullptr) : QObject(parent) { connect(m_ftp, QFtp::stateChanged, this, FtpClient::onStateChanged); connect(m_ftp, QFtp::commandFinished, this, FtpClient::onCommandFinished); connect(m_ftp, QFtp::dataTransferProgress, this, FtpClient::onProgress); connect(m_ftp, QFtp::done, this, FtpClient::onDone); } void connectTo(const QString host, quint16 port, const QString user, const QString pwd) { m_ftp.connectToHost(host, port); // 命令 1 m_ftp.login(user, pwd); // 命令 2等命令 1 完成后自动发 USER/PASS m_ftp.cd(/upload); // 命令 3依次排队 } private: QFtp m_ftp; };connectToHost(host, port)的port默认 21非标准端口必须显式传。login(user, pwd)如果用户名密码为空会发匿名登录anonymous。三行连写不会乱序因为addCommand在HostLookup、Connecting状态下只会入队。真正的坑在错误处理上如果命令 1 失败命令 2 和 3 依然会依次回调commandFinished(id, true)所以业务层要有个m_ok标志位一旦前面失败就后面全跳过别傻乎乎地按 id 一条条处理。3.3 数据连接PASV 响应解析与 227 报文FTP 的控制连接和数据连接是两条 TCP。被动模式下客户端发PASV服务端回一行形如227 Entering Passive Mode (192,168,1,10,19,137)把 IP 和端口用逗号分隔编码在括号里端口是两个字节拼出来的。// 简化自 qftp.cpp 中处理 227 响应的部分 static bool parsePasvReply(const QByteArray reply, QHostAddress *addr, quint16 *port) { const int open reply.indexOf((); const int close reply.indexOf(), open); if (open 0 || close 0) return false; const QListQByteArray nums reply.mid(open 1, close - open - 1).split(,); if (nums.size() ! 6) return false; const QString ip QString(%1.%2.%3.%4) .arg(nums[0].toInt()).arg(nums[1].toInt()) .arg(nums[2].toInt()).arg(nums[3].toInt()); *addr QHostAddress(ip); // 端口 高字节 * 256 低字节注意是大端语义 *port static_castquint16(nums[4].toInt() * 256 nums[5].toInt()); return true; }nums[4] * 256 nums[5]这个计算是硬性的漏了乘 256 就会连到一个完全不存在的端口上然后控制连接一直显示「数据传输中」却不结束。还有一点部分服务端在 NAT 后面返回的是内网 IP客户端直连会失败稳妥做法是忽略报文里的 IP、只用端口复用控制连接的那个地址这个改动在qftp.cpp里只需要一行。3.4 信号面dataTransferProgress、commandFinished、done 怎么配合三个信号的语义要分清不然进度条和结果判断一定错乱。dataTransferProgress(done, total)只在真正传数据时发total可能是 -1服务端没给文件大小。commandFinished(id, error)每条命令结束都发一次。done(error)只在队列清空、进入空闲态时发一次是判断「整批操作结束了」的可靠信号。void FtpClient::upload(const QString localPath, const QString remoteName) { m_file new QFile(localPath, this); if (!m_file-open(QIODevice::ReadOnly)) { // 必须由调用方打开 emit finished(false, 本地文件打不开); return; } m_putId m_ftp.put(m_file, remoteName, QFtp::Binary); // 异步立即返回 id } void FtpClient::onProgress(qint64 done, qint64 total) { // total 可能为 -1UI 上要么显示不确定进度要么用本地文件大小兜底 emit progress(done, total 0 ? total : m_file-size()); } void FtpClient::onDone(bool error) { if (m_file) { m_file-close(); m_file-deleteLater(); m_file nullptr; } emit finished(!error, error ? m_ftp.errorString() : QStringLiteral(ok)); }注意put传进去的QFile必须是已经open(ReadOnly)的QFtp 只负责从里面读不负责打开和关闭。关文件的时机也很讲究一定要等done之后再close提前关会导致传输中途读到空数据最后上传成功但远端文件是 0 字节——这个坑我在第 5 章单独拎出来讲。4. 双平台跑通Linux/Windows 编译、最小 demo 与验证清单4.1 Linux 下的编译与链接把源码放进3rdparty/qtftp改好.pro之后标准流程走一遍就行cd your_project mkdir -p build cd build qmake ../your_project.pro CONFIGrelease make -j$(nproc) ./your_appCONFIGrelease建议显式加上debug 版在没有调试需求时会拖慢传输线程。编译期如果报qftp_p.h: No such file or directory说明私有头路径没加进INCLUDEPATH去看源码里qftp_p.h到底在src/qftp/还是src/qftp/private/按实际位置补。链接期报undefined reference to QFtp::QFtp()八成是SOURCES里漏了qftp.cppqmake 不会提示你少文件只会静静地把库链成残缺的。Linux 上还有一个运行时的注意点被动模式下客户端会主动去连服务端报出来的高端口如果目标机器的防火墙只放了 21数据连接就会一直超时。测试阶段先在服务端所在机器上systemctl stop firewalld或者临时开一段端口范围确认链路能通之后再收敛规则。4.2 Windows 下 MSVC 与 MinGW 的差异Windows 上最大的差异不是编译是编码。MSVC 默认按本地代码页解释源文件里的字符串字面量源码里如果有中文注释或中文路径常量MinGW 编得过、MSVC 可能报 C4819 警告甚至乱码。稳妥做法是两个工具链都加一条# MSVC 下强制源码按 UTF-8 解析避免中文常量乱码 msvc: QMAKE_CXXFLAGS /utf-8 # MinGW 侧显式指定执行字符集 win32-g: QMAKE_CXXFLAGS -finput-charsetUTF-8 -fexec-charsetUTF-8另一个差异是QFile的路径。Windows 下用户目录里可能带中文QFile本身处理没问题但如果你自己用toLocal8Bit()转成char*再交给别的地方就会丢字符。统一走QString只在QFtp内部发命令时才涉及编码转换。最后是链接静态库qtftp.lib在 MSVC 下要确认运行时库一致都是/MT或都是/MD混用会在链接阶段报一堆LNK2005重复符号。4.3 最小可运行 demo上传一个文件并回读校验编过不等于跑通写个二十行的 demo 把整条链路走一遍最快int main(int argc, char *argv[]) { QCoreApplication app(argc, argv); FtpClient client; QObject::connect(client, FtpClient::progress, [](qint64 d, qint64 t) { qInfo() progress d / t; }); QObject::connect(client, FtpClient::finished, [app](bool ok, const QString msg) { qInfo() (ok ? OK : FAIL) msg; app.exit(ok ? 0 : 1); // 用退出码给 CI 判断 }); client.connectTo(127.0.0.1, 21, tester, tester); client.upload(/tmp/dev.log, /upload/dev.log); QTimer::singleShot(30000, app, [app] { // 兜底超时防止永远挂着 qWarning() timeout; app.exit(2); }); return app.exec(); }connectTo和upload都是异步的exec()之前就已经排好队了所以不需要手动等待。singleShot那个兜底定时器别省QFtp 自身没有超时机制服务端不响应时会永远挂着CI 里就是无限等待。退出码设计成 0/1/2 三档脚本就能区分「成功」「协议失败」「超时」三种情况。4.4 跑通之后的验证清单看到「OK」不等于完事我一般会按下面几条过一遍再交付远端文件大小和本地一致ls -l对一下二进制文件用md5sum或certutil -hashfile比对文本模式传输会把\r\n改写二进制必须用QFtp::Binary断网重连一次看客户端是否能干净地回到Unconnected状态连续跑十次观察有没有内存增长put里的QFile如果没deleteLater会稳定泄漏。这几条走完才算真正在 Linux/Windows 两个平台测试过。5. 避坑与排查五条踩过的记录5.1 上传成功但文件是 0 字节现象控制台打印226 Transfer completedone(false)也正常回调但登录服务端一看远端文件大小是 0。原因QFtp::put传进去的QIODevice在传输过程中被提前close()或者被delete了。QFtp 是边读边发的命令入队后你立刻close它读到的就是空。解决QFile的生命周期绑到done()信号上在onDone里再close()和deleteLater()。另外put之前一定要检查isOpen()和size() 0源头就是空的传上去当然也是空的。5.2 中文路径在 listInfo 里变乱码现象list()之后QUrlInfo::name()返回的中文全是问号或者乱码英文目录正常。原因FTP 协议本身没有规定文件名编码服务端多半按 GBK 或本地代码页发而qftp.cpp内部按 Latin-1 解析字节流一对不上就乱。解决在listInfo回调里做一次重编码。取原始字节用QTextCodec::codecForName(GBK)解码再转成QStringvoid onListInfo(const QUrlInfo info) { // 服务端是 GBK 时名字需要二次解码 QTextCodec *codec QTextCodec::codecForName(GBK); const QString name codec-toUnicode(info.name().toLatin1()); qInfo() name info.size() info.isDir(); }如果服务端是 UTF-8把GBK换掉就行。稳妥的做法是把编码做成配置项接不同服务端时改配置不改代码。5.3 主动模式在 Windows 上必挂现象Linux 上一切正常换到 Windows 开发机登录成功、list一直不返回最后超时。原因QFtp::setTransferMode(QFtp::Active)是让服务端回连客户端Windows 上默认防火墙会拦掉这个入站连接而 Linux 测试机没开防火墙所以没暴露。解决默认就用QFtp::Passive这也是 QFtp 的默认值别手动切 Active。确实需要主动模式的内网环境得在客户端放行入站端口范围并在connectToHost之前调setTransferMode顺序错了不生效。5.4 命令卡死不动没有超时现象网络抖动一下之后客户端界面一直转圈日志停在上一条命令重启才能恢复。原因QFtp 没有内建超时控制连接的 socket 如果进入半开状态命令永远等不到响应队列就堵死了。解决自己加看门狗。发命令时记下QElapsedTimercommandFinished回调里重置一个QTimer每 5 秒检查一次超过阈值就m_ftp.abort()再close()然后走重连流程。abort()会清空待发队列所以重连之后业务层要把未完成的命令重新入队。5.5 重复 connectToHost 导致状态错乱现象断线重连逻辑里连续调了两次connectToHost之后stateChanged收到一串莫名其妙的值loggedIn之后再也没触发。原因connectToHost是入队不是立即执行第二次调用时第一次还没结束两条连接命令叠在一起状态机在两个Connecting之间来回跳。解决重连前先判断m_ftp.state()不是Unconnected就先close()并等stateChanged(Unconnected)再发起新连接。用一个bool m_reconnecting做互斥防止信号回调里再次触发重连形成递归。6. 二次开发在 QFtp 上接 TLS、续传与重连的三处改造第一处改造是把明文换成加密。qftp.cpp里控制连接是QTcpSocket把它换成QSslSocket在connectToHost之后调startClientEncryption()连上后先发AUTH TLS再发PBSZ 0和PROT P把数据连接也切到加密。改动集中在私有类的 socket 类型和几处connectToHost调用工作量不大但要确认目标服务端支持显式 TLS不支持的会回500得留降级开关。第二处是断点续传。QFtp 没有直接接口但rawCommand能发裸命令// 先从远端取已存在的大小再从该偏移续传 const qint64 offset remoteFileSize(remoteName); // 用 SIZE 命令或 listInfo 拿 if (offset 0) { m_file.seek(offset); m_ftp.rawCommand(QString(REST %1).arg(offset)); // 只对下一条 RETR/STOR 生效 } m_ftp.put(m_file, remoteName, QFtp::Binary);REST是「一次性」的设完必须紧跟传输命令中间插了别的命令就失效。另外服务端必须支持REST STREAM很多简易服务端只支持REST对下载生效上传续传要实测。第三处是重连状态机把第 5 章那几条揉成一个封装连接超时、命令超时、异常断开三种情况统一走reset()→connectToHost→ 重放未完成命令。我一般会维护一个QQueuePendingCmdcommandFinished成功就出队失败就按次数退避重试超过三次直接抛给上层。从那以后我每次接 FTP 相关的活都强制先跑一遍「小文件上传、大文件上传、断网重连、中文目录遍历」这四个用例不管源码标没标已测试。别人测过是别人的环境你的服务端、防火墙、编码设置都可能不一样。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/29 5:47:29 · 阅读 1.2k QFtp源码接入Qt工程：跨平台FTP传输与避坑实战
简介QFTP是一套基于FTP协议的跨平台客户端源码面向使用C/Qt开发文件传输功能的开发者以及希望理解FTP通信实现细节的学习者。它可用于在桌面应用、IDE插件或文件管理工具中集成上传、下载能力也适合作为网络编程与协议解析的参考实现。压缩包共4个文件由2个cpp源文件和2个h头文件组成整体约24KB体量轻便其中源文件承载连接管理、FTP命令收发与数据传输逻辑头文件则声明对外接口和URL信息处理结构便于按模块阅读与二次开发。该源码已在Linux和Windows平台完成测试涉及跨平台API适配与基本功能验证已有297人学习或浏览。读者可从中了解FTP连接建立、LIST/RETR/STOR等命令执行、响应与错误处理以及URL主机、端口、认证信息的解析方式并据此裁剪、扩展或嵌入自有项目获得可定制的FTP客户端基础。1. 为什么还要捡起 QFTP 源码给设备运维工具加一个日志回传功能的时候需求很朴素每天凌晨把产线工控机上的日志目录整个拉回来顺便把新固件推上去。设备端只开了 21 端口除了 FTP 没别的口子可用。翻到 Qt 才发现从 Qt 5 开始 QFtp 就不再随 QtNetwork 一起发布了官方把它拆成独立模块必须自己把源码编进工程。这份 QFTP 源码已经在 Linux/Windows 两个平台完成过测试qmake 工程直接能编这正是它最值钱的地方FTP 协议本身不复杂真正麻烦的是跨平台里那一堆连接状态、被动模式报文解析和字节编码细节有人替你趟过一遍能省掉大半天。它适合手里已经有 Qt 工程、又必须跟老式 FTP 服务端打交道的人当成内部插件模块引进来的那种用法。2. 源码骨架与接入方式qtftp 模块怎么塞进现有 Qt 工程2.1 目录与文件职责拿到源码先别急着编先把文件职责摸清楚。QFtp 这一套东西不大核心就几个文件真正干活的都在qftp.cpp里。它没有第三方依赖只吃 QtCore 和 QtNetwork所以接进任何 Qt 工程都不会引入版本冲突这也是我一般优先选它的原因。文件职责改动频率qftp.h对外接口QFtp类声明、Command/State/TransferType枚举几乎不改qftp.cpp协议实现命令队列、控制连接、PASV/PORT 数据连接、响应解析改编码、加 TLS 时才动qftp_p.h私有实现QFtpPrivate持有 socket 和命令队列加字段时动qurlinfo.h/.cppQUrlInfo封装LIST返回的单条目录项基本不动qtftp.pro/CMakeLists.txt模块自身的构建脚本按需理解这张表的关键在于QFtp是纯异步的所有成员函数connectToHost、login、put都是「把命令塞进队列然后立刻返回一个整数 id」真正发字节是在事件循环里做的。这是后面所有调试思路的基础别把它当成阻塞式 API 用。2.2 qmake 子工程接入最省事的办法是把整个源码目录丢进工程的3rdparty/然后让.pro直接引用。不要试图装到系统 Qt 目录里那样换个开发机就得重来一遍血泪经验。QT core network # 源码放在工程内的 3rdparty/qtftp跟着仓库一起走 INCLUDEPATH $$PWD/3rdparty/qtftp/src/qftp DEPENDPATH $$PWD/3rdparty/qtftp/src/qftp HEADERS $$PWD/3rdparty/qtftp/src/qftp/qftp.h \ $$PWD/3rdparty/qtftp/src/qftp/qurlinfo.h SOURCES $$PWD/3rdparty/qtftp/src/qftp/qftp.cpp \ $$PWD/3rdparty/qtftp/src/qftp/qurlinfo.cppINCLUDEPATH让#include QFtp或#include qftp.h能定位到头文件DEPENDPATH是给 qmake 生成依赖关系用的漏了它改头文件不会触发重编。QT network不能少qftp.cpp里用到QTcpSocket、QHostAddress、QUrlInfo这些类。如果qftp_p.h在private/子目录下记得把那个路径也加进INCLUDEPATH否则编译时会报找不到私有头。2.3 CMake 接入与静态库导出新工程基本都用 CMake 了做法是把 qtftp 编成一个静态库业务代码只链这个 target头文件路径通过PUBLIC自动传递出去。add_library(qtftp STATIC ${CMAKE_CURRENT_SOURCE_DIR}/src/qftp/qftp.cpp ${CMAKE_CURRENT_SOURCE_DIR}/src/qftp/qurlinfo.cpp ) # PUBLIC谁链 qtftp谁就自动拿到这两个头文件搜索路径 target_include_directories(qtftp PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/src/qftp ${CMAKE_CURRENT_SOURCE_DIR}/src/qftp/private ) target_link_libraries(qtftp PUBLIC Qt5::Core Qt5::Network) # Linux 下要被主程序动态链接时必须开 PICWindows 无所谓 set_target_properties(qtftp PROPERTIES POSITION_INDEPENDENT_CODE ON)POSITION_INDEPENDENT_CODE ON这一行在 Linux 上是必须的忘了它主程序一旦是共享库或者开了-fPIC链接阶段就会甩出一堆 relocation 错误看着像玄学其实就这一个开关。业务侧只需要target_link_libraries(your_app PRIVATE qtftp)其余不用管。2.4 平台差异Linux 与 Windows 上要额外关注的三个点第一是头文件包含大小写。Linux 文件系统区分大小写代码里写#include QFtp在 Windows 上能过、到 Linux 直接翻车统一写成小写的qftp.h最稳。第二是文件路径分隔符QFtp::put的远端文件名参数必须用/本地路径交给QFile处理别自己拼字符串。第三是网络行为Linux 下默认的被动模式一般畅通Windows 上如果开发机装了安全软件被动模式的随机高端口有可能被拦表现是控制连接正常、数据连接永远挂住这一点在第 5 章会展开。3. 核心链路拆解一条 put 命令从入队到数据连接关闭3.1 QFtpPrivate 的命令队列与状态机qftp.cpp的主干是一个命令队列加一个状态机。QFtpPrivate内部维护QListCommand每条Command记录命令类型ConnectToHost、Login、Put、Get、List……、参数和返回给调用方的 id。QFtp的每个公开函数实际只做三件事构造 Command、addCommand入队、返回 id。// 简化后的主干展示命令入队的思路 int QFtp::put(QIODevice *dev, const QString file, TransferType type) { Q_D(QFtp); if (!dev) return -1; return d-addCommand(Put, file, dev); // 返回自增 id调用方拿它对齐信号 } int QFtpPrivate::addCommand(Command::Type type, const QString arg, QIODevice *dev) { Command cmd; cmd.type type; cmd.id nextId; // 全局自增commandStarted/commandFinished 靠它配对 cmd.arg arg; cmd.dev dev; pending.append(cmd); if (state Unconnected || state Idle) startNextCommand(); // 空闲就立刻发忙就排队等 done() return cmd.id; }这里的id是整个异步模型的锚点。你发出去五条命令commandStarted(id)和commandFinished(id, error)会按 id 一一回调业务层要靠 id 判断「刚才失败的那条到底是登录还是上传」。state用来防止并发Running状态下新命令只入队不发送startNextCommand在每收到226/250响应后才推下一条。理解了这一层就不会出现「连着调三次connectToHost结果状态乱套」的翻车现场。3.2 握手阶段connectToHost、login、cd 的时序因为命令是排队的连着写三行不需要嵌套回调这是 QFtp 用起来最舒服的地方class FtpClient : public QObject { Q_OBJECT public: explicit FtpClient(QObject *parent nullptr) : QObject(parent) { connect(m_ftp, QFtp::stateChanged, this, FtpClient::onStateChanged); connect(m_ftp, QFtp::commandFinished, this, FtpClient::onCommandFinished); connect(m_ftp, QFtp::dataTransferProgress, this, FtpClient::onProgress); connect(m_ftp, QFtp::done, this, FtpClient::onDone); } void connectTo(const QString host, quint16 port, const QString user, const QString pwd) { m_ftp.connectToHost(host, port); // 命令 1 m_ftp.login(user, pwd); // 命令 2等命令 1 完成后自动发 USER/PASS m_ftp.cd(/upload); // 命令 3依次排队 } private: QFtp m_ftp; };connectToHost(host, port)的port默认 21非标准端口必须显式传。login(user, pwd)如果用户名密码为空会发匿名登录anonymous。三行连写不会乱序因为addCommand在HostLookup、Connecting状态下只会入队。真正的坑在错误处理上如果命令 1 失败命令 2 和 3 依然会依次回调commandFinished(id, true)所以业务层要有个m_ok标志位一旦前面失败就后面全跳过别傻乎乎地按 id 一条条处理。3.3 数据连接PASV 响应解析与 227 报文FTP 的控制连接和数据连接是两条 TCP。被动模式下客户端发PASV服务端回一行形如227 Entering Passive Mode (192,168,1,10,19,137)把 IP 和端口用逗号分隔编码在括号里端口是两个字节拼出来的。// 简化自 qftp.cpp 中处理 227 响应的部分 static bool parsePasvReply(const QByteArray reply, QHostAddress *addr, quint16 *port) { const int open reply.indexOf((); const int close reply.indexOf(), open); if (open 0 || close 0) return false; const QListQByteArray nums reply.mid(open 1, close - open - 1).split(,); if (nums.size() ! 6) return false; const QString ip QString(%1.%2.%3.%4) .arg(nums[0].toInt()).arg(nums[1].toInt()) .arg(nums[2].toInt()).arg(nums[3].toInt()); *addr QHostAddress(ip); // 端口 高字节 * 256 低字节注意是大端语义 *port static_castquint16(nums[4].toInt() * 256 nums[5].toInt()); return true; }nums[4] * 256 nums[5]这个计算是硬性的漏了乘 256 就会连到一个完全不存在的端口上然后控制连接一直显示「数据传输中」却不结束。还有一点部分服务端在 NAT 后面返回的是内网 IP客户端直连会失败稳妥做法是忽略报文里的 IP、只用端口复用控制连接的那个地址这个改动在qftp.cpp里只需要一行。3.4 信号面dataTransferProgress、commandFinished、done 怎么配合三个信号的语义要分清不然进度条和结果判断一定错乱。dataTransferProgress(done, total)只在真正传数据时发total可能是 -1服务端没给文件大小。commandFinished(id, error)每条命令结束都发一次。done(error)只在队列清空、进入空闲态时发一次是判断「整批操作结束了」的可靠信号。void FtpClient::upload(const QString localPath, const QString remoteName) { m_file new QFile(localPath, this); if (!m_file-open(QIODevice::ReadOnly)) { // 必须由调用方打开 emit finished(false, 本地文件打不开); return; } m_putId m_ftp.put(m_file, remoteName, QFtp::Binary); // 异步立即返回 id } void FtpClient::onProgress(qint64 done, qint64 total) { // total 可能为 -1UI 上要么显示不确定进度要么用本地文件大小兜底 emit progress(done, total 0 ? total : m_file-size()); } void FtpClient::onDone(bool error) { if (m_file) { m_file-close(); m_file-deleteLater(); m_file nullptr; } emit finished(!error, error ? m_ftp.errorString() : QStringLiteral(ok)); }注意put传进去的QFile必须是已经open(ReadOnly)的QFtp 只负责从里面读不负责打开和关闭。关文件的时机也很讲究一定要等done之后再close提前关会导致传输中途读到空数据最后上传成功但远端文件是 0 字节——这个坑我在第 5 章单独拎出来讲。4. 双平台跑通Linux/Windows 编译、最小 demo 与验证清单4.1 Linux 下的编译与链接把源码放进3rdparty/qtftp改好.pro之后标准流程走一遍就行cd your_project mkdir -p build cd build qmake ../your_project.pro CONFIGrelease make -j$(nproc) ./your_appCONFIGrelease建议显式加上debug 版在没有调试需求时会拖慢传输线程。编译期如果报qftp_p.h: No such file or directory说明私有头路径没加进INCLUDEPATH去看源码里qftp_p.h到底在src/qftp/还是src/qftp/private/按实际位置补。链接期报undefined reference to QFtp::QFtp()八成是SOURCES里漏了qftp.cppqmake 不会提示你少文件只会静静地把库链成残缺的。Linux 上还有一个运行时的注意点被动模式下客户端会主动去连服务端报出来的高端口如果目标机器的防火墙只放了 21数据连接就会一直超时。测试阶段先在服务端所在机器上systemctl stop firewalld或者临时开一段端口范围确认链路能通之后再收敛规则。4.2 Windows 下 MSVC 与 MinGW 的差异Windows 上最大的差异不是编译是编码。MSVC 默认按本地代码页解释源文件里的字符串字面量源码里如果有中文注释或中文路径常量MinGW 编得过、MSVC 可能报 C4819 警告甚至乱码。稳妥做法是两个工具链都加一条# MSVC 下强制源码按 UTF-8 解析避免中文常量乱码 msvc: QMAKE_CXXFLAGS /utf-8 # MinGW 侧显式指定执行字符集 win32-g: QMAKE_CXXFLAGS -finput-charsetUTF-8 -fexec-charsetUTF-8另一个差异是QFile的路径。Windows 下用户目录里可能带中文QFile本身处理没问题但如果你自己用toLocal8Bit()转成char*再交给别的地方就会丢字符。统一走QString只在QFtp内部发命令时才涉及编码转换。最后是链接静态库qtftp.lib在 MSVC 下要确认运行时库一致都是/MT或都是/MD混用会在链接阶段报一堆LNK2005重复符号。4.3 最小可运行 demo上传一个文件并回读校验编过不等于跑通写个二十行的 demo 把整条链路走一遍最快int main(int argc, char *argv[]) { QCoreApplication app(argc, argv); FtpClient client; QObject::connect(client, FtpClient::progress, [](qint64 d, qint64 t) { qInfo() progress d / t; }); QObject::connect(client, FtpClient::finished, [app](bool ok, const QString msg) { qInfo() (ok ? OK : FAIL) msg; app.exit(ok ? 0 : 1); // 用退出码给 CI 判断 }); client.connectTo(127.0.0.1, 21, tester, tester); client.upload(/tmp/dev.log, /upload/dev.log); QTimer::singleShot(30000, app, [app] { // 兜底超时防止永远挂着 qWarning() timeout; app.exit(2); }); return app.exec(); }connectTo和upload都是异步的exec()之前就已经排好队了所以不需要手动等待。singleShot那个兜底定时器别省QFtp 自身没有超时机制服务端不响应时会永远挂着CI 里就是无限等待。退出码设计成 0/1/2 三档脚本就能区分「成功」「协议失败」「超时」三种情况。4.4 跑通之后的验证清单看到「OK」不等于完事我一般会按下面几条过一遍再交付远端文件大小和本地一致ls -l对一下二进制文件用md5sum或certutil -hashfile比对文本模式传输会把\r\n改写二进制必须用QFtp::Binary断网重连一次看客户端是否能干净地回到Unconnected状态连续跑十次观察有没有内存增长put里的QFile如果没deleteLater会稳定泄漏。这几条走完才算真正在 Linux/Windows 两个平台测试过。5. 避坑与排查五条踩过的记录5.1 上传成功但文件是 0 字节现象控制台打印226 Transfer completedone(false)也正常回调但登录服务端一看远端文件大小是 0。原因QFtp::put传进去的QIODevice在传输过程中被提前close()或者被delete了。QFtp 是边读边发的命令入队后你立刻close它读到的就是空。解决QFile的生命周期绑到done()信号上在onDone里再close()和deleteLater()。另外put之前一定要检查isOpen()和size() 0源头就是空的传上去当然也是空的。5.2 中文路径在 listInfo 里变乱码现象list()之后QUrlInfo::name()返回的中文全是问号或者乱码英文目录正常。原因FTP 协议本身没有规定文件名编码服务端多半按 GBK 或本地代码页发而qftp.cpp内部按 Latin-1 解析字节流一对不上就乱。解决在listInfo回调里做一次重编码。取原始字节用QTextCodec::codecForName(GBK)解码再转成QStringvoid onListInfo(const QUrlInfo info) { // 服务端是 GBK 时名字需要二次解码 QTextCodec *codec QTextCodec::codecForName(GBK); const QString name codec-toUnicode(info.name().toLatin1()); qInfo() name info.size() info.isDir(); }如果服务端是 UTF-8把GBK换掉就行。稳妥的做法是把编码做成配置项接不同服务端时改配置不改代码。5.3 主动模式在 Windows 上必挂现象Linux 上一切正常换到 Windows 开发机登录成功、list一直不返回最后超时。原因QFtp::setTransferMode(QFtp::Active)是让服务端回连客户端Windows 上默认防火墙会拦掉这个入站连接而 Linux 测试机没开防火墙所以没暴露。解决默认就用QFtp::Passive这也是 QFtp 的默认值别手动切 Active。确实需要主动模式的内网环境得在客户端放行入站端口范围并在connectToHost之前调setTransferMode顺序错了不生效。5.4 命令卡死不动没有超时现象网络抖动一下之后客户端界面一直转圈日志停在上一条命令重启才能恢复。原因QFtp 没有内建超时控制连接的 socket 如果进入半开状态命令永远等不到响应队列就堵死了。解决自己加看门狗。发命令时记下QElapsedTimercommandFinished回调里重置一个QTimer每 5 秒检查一次超过阈值就m_ftp.abort()再close()然后走重连流程。abort()会清空待发队列所以重连之后业务层要把未完成的命令重新入队。5.5 重复 connectToHost 导致状态错乱现象断线重连逻辑里连续调了两次connectToHost之后stateChanged收到一串莫名其妙的值loggedIn之后再也没触发。原因connectToHost是入队不是立即执行第二次调用时第一次还没结束两条连接命令叠在一起状态机在两个Connecting之间来回跳。解决重连前先判断m_ftp.state()不是Unconnected就先close()并等stateChanged(Unconnected)再发起新连接。用一个bool m_reconnecting做互斥防止信号回调里再次触发重连形成递归。6. 二次开发在 QFtp 上接 TLS、续传与重连的三处改造第一处改造是把明文换成加密。qftp.cpp里控制连接是QTcpSocket把它换成QSslSocket在connectToHost之后调startClientEncryption()连上后先发AUTH TLS再发PBSZ 0和PROT P把数据连接也切到加密。改动集中在私有类的 socket 类型和几处connectToHost调用工作量不大但要确认目标服务端支持显式 TLS不支持的会回500得留降级开关。第二处是断点续传。QFtp 没有直接接口但rawCommand能发裸命令// 先从远端取已存在的大小再从该偏移续传 const qint64 offset remoteFileSize(remoteName); // 用 SIZE 命令或 listInfo 拿 if (offset 0) { m_file.seek(offset); m_ftp.rawCommand(QString(REST %1).arg(offset)); // 只对下一条 RETR/STOR 生效 } m_ftp.put(m_file, remoteName, QFtp::Binary);REST是「一次性」的设完必须紧跟传输命令中间插了别的命令就失效。另外服务端必须支持REST STREAM很多简易服务端只支持REST对下载生效上传续传要实测。第三处是重连状态机把第 5 章那几条揉成一个封装连接超时、命令超时、异常断开三种情况统一走reset()→connectToHost→ 重放未完成命令。我一般会维护一个QQueuePendingCmdcommandFinished成功就出队失败就按次数退避重试超过三次直接抛给上层。从那以后我每次接 FTP 相关的活都强制先跑一遍「小文件上传、大文件上传、断网重连、中文目录遍历」这四个用例不管源码标没标已测试。别人测过是别人的环境你的服务端、防火墙、编码设置都可能不一样。希望帮到你。本文还有配套的精品资源点击获取