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是纯异步的，所有成员函数（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.cpp

INCLUDEPATH让#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 下要被主程序动态链接时必须开 PIC，Windows 无所谓 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内部维护QList<Command>，每条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 QList<QByteArray> 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_cast<quint16>(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 可能为 -1，UI 上要么显示不确定进度，要么用本地文件大小兜底 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 CONFIG+=release make -j$(nproc) ./your_app

CONFIG+=release建议显式加上，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.cpp，qmake 不会提示你少文件，只会静静地把库链成残缺的。

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-charset=UTF-8 -fexec-charset=UTF-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 complete，done(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")解码再转成QString：

void 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 如果进入半开状态，命令永远等不到响应，队列就堵死了。

解决：自己加看门狗。发命令时记下QElapsedTimer，commandFinished回调里重置；一个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→ 重放未完成命令。我一般会维护一个QQueue<PendingCmd>，commandFinished成功就出队，失败就按次数退避重试，超过三次直接抛给上层。

从那以后我每次接 FTP 相关的活，都强制先跑一遍「小文件上传、大文件上传、断网重连、中文目录遍历」这四个用例，不管源码标没标"已测试"。别人测过是别人的环境，你的服务端、防火墙、编码设置都可能不一样。希望帮到你。

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