尧图网站建设 
简介QFTP源码是一份面向C与Qt开发者的跨平台FTP客户端实现参考适合需要理解FTP协议细节、或希望将文件传输能力集成进自有项目的开发者学习与二次开发。资源包共4个文件以2个cpp实现文件与2个h头文件为主压缩包约24KB体量轻巧却结构完整实现文件承载连接管理、命令收发与数据传输逻辑头文件则对外暴露类接口与URL信息解析声明便于快速把握模块划分。目前已有296人学习下载说明其在同类源码中具备一定参考热度。通过研读这套代码读者可以掌握FTP连接建立、LIST/RETR/STOR等命令执行、响应与错误处理的具体写法理解URL解析如何提取主机、端口与认证信息并借鉴其跨平台适配思路将同一份源码在Linux与Windows上编译运行为自建FTP工具或插件式集成打下基础。1. QFTP 源码拆包一份能在 Linux 和 Windows 双端跑通的 FTP 实现手里这份 QFTP 源码是我最近在整理嵌入式设备文件传输方案时翻出来的。它不是什么新潮玩意而是一套用 C 写的 FTP 客户端/服务端实现核心价值在于——同一份代码在 Linux 和 Windows 上都能编译、能跑、能传文件。做过跨平台网络编程的人都知道Socket 接口在两边的差异能把人逼疯Windows 要WSAStartupLinux 直接socket()Windows 的closesocket到 Linux 变成close阻塞和非阻塞的默认行为也不一样。QFTP 把这些差异用一层薄薄的封装抹平了你拿到的是一套可以直接嵌入自己项目的传输模块而不是一个只能看不能改的玩具。适合谁用如果你在做嵌入式 Linux 设备的数据回传、工控机的日志同步、或者 Windows 服务端和 Linux 采集端之间的文件搬运这份源码能省掉你至少一周的跨平台适配时间。它不依赖 Qt 框架虽然名字带 Q但实际是轻量级实现编译出来就是一个静态库或几个源文件塞进现有工程就能用。下面我从代码结构、编译方式、参数配置到实际踩坑一步步拆给你看。2. 源码结构与跨平台适配层先看懂再动手2.1 目录布局与核心类职责拿到源码包后先别急着make。花十分钟把目录结构过一遍后面改代码时能少走很多弯路。典型的 QFTP 源码包结构是这样的qftp/ ├── include/ │ ├── qftp.h # 对外暴露的接口声明 │ ├── qftpsocket.h # Socket 封装层 │ └── qftpsession.h # 会话管理 ├── src/ │ ├── qftp.cpp # 主逻辑实现 │ ├── qftpsocket.cpp # 跨平台 Socket 适配 │ ├── qftpsession.cpp # 命令解析与状态机 │ └── qftputils.cpp # 字符串、路径处理工具 ├── examples/ │ ├── client_demo.cpp │ └── server_demo.cpp ├── CMakeLists.txt └── README.md核心类就三个QFtpSocket负责所有和系统 Socket API 打交道的事QFtpSession维护单个连接的状态机登录、切换目录、传输模式QFtp是对外门面你调它的connectToHost、login、get、put就行。这种分层的好处是如果你要换底层网络库比如换成 libuv 或 asio只需要动QFtpSocket一个文件。QFtpSocket里的跨平台适配是重点。Windows 下需要#include winsock2.h并链接ws2_32.libLinux 下则是sys/socket.h和netinet/in.h。源码里用#ifdef _WIN32做了条件编译把SOCKET类型、INVALID_SOCKET、SOCKET_ERROR这些差异统一成了自定义的qftp_socket_t和错误码。你拿到代码后第一件事就是确认这个适配层有没有漏掉你目标平台的宏定义。2.2 编译前的环境检查与依赖确认在 Linux 上编译你需要 g 7 以上或 clang 6 以上CMake 3.10 以上。Windows 上推荐用 Visual Studio 2019 或 MinGW-w64。先跑一遍环境检查命令# Linux 下检查编译器和 CMake 版本 g --version cmake --version # Windows 下如果用 MinGW检查 g 是否在 PATH 里 g --version如果版本不够Linux 下用sudo apt install build-essential cmake补齐Windows 下装个 MSYS2 或者直接上 VS 的“使用 C 的桌面开发”工作负载。注意Windows 下如果用 VS 编译CMake 生成工程时要指定-G Visual Studio 16 2019否则默认可能找到 MinGW 的 Makefile 生成器后面链接ws2_32.lib会出问题。依赖方面QFTP 本身不依赖 OpenSSL除非你要做 FTPS也不依赖 zlib。但如果你要传二进制文件建议在编译时打开QFTP_BINARY_MODE宏否则 Windows 下文本模式会把\r\n转成\n传过去的文件大小对不上。这个坑我后面会细说。2.3 用 CMake 生成双端构建脚本源码包里的CMakeLists.txt已经写好了跨平台逻辑但有几个开关你需要根据实际情况调整。打开文件找到这几行option(QFTP_BUILD_EXAMPLES Build example client and server ON) option(QFTP_ENABLE_SSL Enable FTPS support OFF) option(QFTP_STATIC_LIB Build as static library ON)如果你只是想把 QFTP 嵌到现有工程里把QFTP_BUILD_EXAMPLES关掉QFTP_STATIC_LIB打开编译出来就是一个.a或.lib。然后在你自己的CMakeLists.txt里加add_subdirectory(qftp) target_link_libraries(your_target PRIVATE qftp)Windows 下还需要额外链接系统库if(WIN32) target_link_libraries(qftp PRIVATE ws2_32) endif()Linux 下则不需要额外链接因为 Socket 函数在 libc 里。生成构建系统时Linux 用cmake -B build -DCMAKE_BUILD_TYPEReleaseWindows 用cmake -B build -G Visual Studio 16 2019 -A x64。生成完再cmake --build build --config Release两端都能得到可执行文件和库文件。注意Windows 下如果报error: start the windows daemon from a non-elevated terminal之类的权限错误大概率是你把服务端 demo 当成系统服务跑了。QFTP 的服务端 demo 是普通控制台程序直接双击或从命令行启动即可不需要管理员权限。3. 核心接口调用与参数配置从连接建立到文件传输3.1 建立连接与登录的超时参数QFTP 的连接建立分两步先connectToHost再login。这两个操作都有超时参数默认值分别是 30 秒和 10 秒。在实际项目中我一般会把连接超时调到 5 秒登录超时调到 3 秒因为内网环境下超过这个时间基本就是网络不通或服务没起来没必要干等。#include qftp.h QFtp ftp; ftp.setConnectTimeout(5000); // 连接超时 5 秒 ftp.setLoginTimeout(3000); // 登录超时 3 秒 ftp.setTransferTimeout(30000); // 数据传输超时 30 秒 if (!ftp.connectToHost(192.168.1.100, 21)) { // 连接失败getLastError() 返回错误码 printf(connect failed: %d\n, ftp.getLastError()); return -1; } if (!ftp.login(anonymous, anonymousexample.com)) { printf(login failed: %d\n, ftp.getLastError()); return -1; }setConnectTimeout控制的是 TCP 三次握手的时间底层用select或poll实现非阻塞连接。setLoginTimeout控制的是发送 USER/PASS 命令后等待 230 响应的时间。setTransferTimeout是每次send或recv的等待时间传大文件时可以适当调大但不要超过 60 秒否则网络断了你也不知道。3.2 主动模式与被动模式的选择逻辑FTP 有两种数据连接模式PORT主动和 PASV被动。QFTP 默认用 PASV因为主动模式在客户端有防火墙时基本不可用。但如果你在纯内网环境且服务端在 NAT 后面主动模式反而更稳定。ftp.setPassiveMode(true); // 默认就是 true显式写出来方便阅读 // 如果要用主动模式 ftp.setPassiveMode(false); ftp.setLocalDataPort(0); // 0 表示让系统自动分配端口被动模式下客户端发送 PASV 命令服务端返回一个 IP 和端口客户端主动去连这个端口。主动模式下客户端发送 PORT 命令告诉服务端自己的 IP 和端口服务端反过来连客户端。常见坑是被动模式下服务端返回的是内网 IP客户端在外网就连不上。这时候要么让服务端配置公网 IP要么改用主动模式。QFTP 的setPassiveMode可以在每次传输前动态切换你可以根据网络环境写个探测逻辑。3.3 文件上传下载的完整代码示例下面是一个完整的下载示例包含断点续传的判断逻辑#include qftp.h #include sys/stat.h bool downloadFile(QFtp ftp, const std::string remotePath, const std::string localPath) { // 检查本地文件是否存在决定是否续传 struct stat st; long long offset 0; if (stat(localPath.c_str(), st) 0) { offset st.st_size; } // 设置传输类型为二进制避免 Windows 下换行符转换 ftp.setTransferType(QFtp::Binary); // 打开本地文件追加模式 FILE *fp fopen(localPath.c_str(), offset 0 ? ab : wb); if (!fp) { printf(open local file failed\n); return false; } // 如果 offset 0发送 REST 命令告诉服务端从哪个字节开始传 if (offset 0) { if (!ftp.sendRest(offset)) { printf(REST command failed\n); fclose(fp); return false; } } // 开始下载回调里写文件 bool ok ftp.get(remotePath, [fp](const char *data, int len) { fwrite(data, 1, len, fp); }); fclose(fp); return ok; }setTransferType(QFtp::Binary)这行必须加否则 Windows 下默认是 ASCII 模式传过去的二进制文件会被改坏。sendRest是断点续传的关键它发送REST命令给服务端服务端收到后会把文件指针移到指定位置。注意不是所有 FTP 服务端都支持REST如果返回 502 错误就只能从头传。回调函数里的data和len是本次收到的数据块你直接写文件就行QFTP 内部已经处理了粘包和分包。上传的逻辑类似用ftp.put(localPath, remotePath)但要注意权限问题。如果服务端返回 550 Permission denied检查目标目录的写权限以及登录用户是否有上传权限。4. 避坑与常见问题排查血泪经验换来的五条记录4.1 现象Windows 下编译报错“无法解析的外部符号 __imp__WSAStartup”原因没有链接ws2_32.lib。QFTP 的QFtpSocket在 Windows 下会调用WSAStartup和WSACleanup这两个函数在ws2_32.lib里。CMake 里虽然写了target_link_libraries(qftp PRIVATE ws2_32)但如果你是用 VS 手动建工程很容易漏掉。解决在 VS 的“链接器 → 输入 → 附加依赖项”里加上ws2_32.lib。或者直接在代码里加#pragma comment(lib, ws2_32.lib)这样就不用改工程配置了。4.2 现象Linux 下传输大文件时程序卡死CPU 占用率飙升原因QFtpSocket::recv在非阻塞模式下返回EAGAIN时代码里写了个while(true)循环反复重试没有让出 CPU。这是很多手写 Socket 封装的通病。解决找到qftpsocket.cpp里的recvData函数把忙等待改成select或poll等待可读事件。QFTP 源码里其实已经提供了waitForReadyRead方法你只需要在EAGAIN时调用它而不是空转。修改后 CPU 占用会从 100% 降到 1% 以下。4.3 现象被动模式下连接数据端口超时但控制连接正常原因服务端返回的 PASV 响应里IP 地址是内网地址比如 10.0.0.5而客户端在外网根本路由不到这个地址。这是 FTP 协议的历史遗留问题NAT 环境下很常见。解决两个方案。一是让服务端配置pasv_address为公网 IPvsftpd 里是pasv_address公网IP。二是在 QFTP 里忽略 PASV 返回的 IP直接用控制连接的 IP 加返回的端口。QFTP 提供了setIgnorePasvAddress(true)接口打开后就会用控制连接的地址去连数据端口。4.4 现象传输后的文件 MD5 对不上大小差了几个字节原因Windows 下默认用了 ASCII 传输模式\r\n被转换成了\n或者反过来。文本文件可能看不出来但二进制文件比如 zip、exe一传就坏。解决在每次get或put之前显式调用ftp.setTransferType(QFtp::Binary)。不要依赖默认值因为不同 FTP 服务端的默认模式可能不一样。我一般会在login成功后立刻设置一次后面就不管了。4.5 现象程序退出时在 Windows 下报内存泄漏Linux 下正常原因Windows 下WSAStartup和WSACleanup必须成对调用。QFTP 的QFtpSocket构造函数里调了WSAStartup但析构函数里如果提前return了WSACleanup就不会执行。Linux 下没有这个配对要求所以看不出问题。解决检查QFtpSocket的析构函数确保所有路径都会走到WSACleanup。更稳妥的做法是用 RAII把WSAStartup和WSACleanup封装到一个WsaInitializer类里在main函数开头构造结尾自动析构。5. 进阶技巧用 QFTP 做自动化文件同步与校验5.1 基于时间戳的增量同步策略实际项目中我很少直接调get和put传单个文件而是写一个同步器根据本地和服务端的文件修改时间决定传哪些。QFTP 提供了list命令获取远程目录列表返回的每一行包含权限、大小、日期和文件名。解析这个列表就能拿到远程文件的修改时间。// 获取远程目录列表并解析 std::vectorRemoteFile files; ftp.list(/data, [files](const std::string line) { // 典型行格式-rw-r--r-- 1 user group 1024 Jan 15 10:30 data.log RemoteFile rf; char dateBuf[32]; if (sscanf(line.c_str(), %*s %*d %*s %*s %lld %s %*s %s, rf.size, dateBuf, rf.name) 3) { // 解析日期这里简化处理实际要用 strptime files.push_back(rf); } });拿到远程文件列表后和本地stat的结果对比只传修改时间更新的文件。这样每次同步可能只传几个文件而不是整个目录。注意list返回的日期格式取决于服务端有的用Jan 15 10:30有的用2024-01-15 10:30解析时要兼容。5.2 传输后的完整性校验传完文件后怎么确认没传坏最可靠的方法是对比 MD5。但 FTP 协议本身不提供 MD5 命令你需要自己算。我的做法是传完后在服务端执行md5sum命令通过SITE命令或 SSH把结果和本地算的对比。如果服务端不支持就对比文件大小和最后修改时间虽然不如 MD5 严格但能拦住大部分问题。// 本地算 MD5简化示例实际用 OpenSSL 或自己实现 std::string localMd5 computeMd5(localPath); // 通过 SITE 命令让服务端算 MD5需要服务端支持 std::string remoteMd5; ftp.site(MD5 remotePath, [remoteMd5](const std::string resp) { remoteMd5 resp; }); if (localMd5 ! remoteMd5) { printf(MD5 mismatch! local%s remote%s\n, localMd5.c_str(), remoteMd5.c_str()); // 重传或报错 }如果服务端不支持SITE MD5退而求其次对比文件大小。QFTP 的size命令可以获取远程文件大小和本地stat的结果比一下差一个字节都说明有问题。5.3 断线重连与传输恢复网络不稳定时传输中途断开是常事。QFTP 本身没有自动重连你需要在回调里检测错误码然后重新connectToHost、login、sendRest、继续传。我一般会写一个retryTransfer函数最多重试 3 次每次间隔 5 秒。bool retryDownload(QFtp ftp, const std::string remote, const std::string local, int maxRetry) { for (int i 0; i maxRetry; i) { if (downloadFile(ftp, remote, local)) { return true; } printf(download failed, retry %d/%d\n, i 1, maxRetry); sleep(5); // 重新连接 ftp.disconnect(); ftp.connectToHost(192.168.1.100, 21); ftp.login(user, pass); } return false; }注意重连后sendRest的 offset 要重新从本地文件大小算因为上次可能已经传了一部分。这个逻辑在downloadFile里已经处理了只要本地文件是追加模式打开的重试时会自动从断点继续。从那以后我每次传完文件都强制走一遍 MD5 校验哪怕多花几秒钟也比事后发现文件坏了强。希望帮到你。本文还有配套的精品资源点击获取 QFTP源码拆包：Linux与Windows双端FTP实现与跨平台适配指南
简介QFTP源码是一份面向C与Qt开发者的跨平台FTP客户端实现参考适合需要理解FTP协议细节、或希望将文件传输能力集成进自有项目的开发者学习与二次开发。资源包共4个文件以2个cpp实现文件与2个h头文件为主压缩包约24KB体量轻巧却结构完整实现文件承载连接管理、命令收发与数据传输逻辑头文件则对外暴露类接口与URL信息解析声明便于快速把握模块划分。目前已有296人学习下载说明其在同类源码中具备一定参考热度。通过研读这套代码读者可以掌握FTP连接建立、LIST/RETR/STOR等命令执行、响应与错误处理的具体写法理解URL解析如何提取主机、端口与认证信息并借鉴其跨平台适配思路将同一份源码在Linux与Windows上编译运行为自建FTP工具或插件式集成打下基础。1. QFTP 源码拆包一份能在 Linux 和 Windows 双端跑通的 FTP 实现手里这份 QFTP 源码是我最近在整理嵌入式设备文件传输方案时翻出来的。它不是什么新潮玩意而是一套用 C 写的 FTP 客户端/服务端实现核心价值在于——同一份代码在 Linux 和 Windows 上都能编译、能跑、能传文件。做过跨平台网络编程的人都知道Socket 接口在两边的差异能把人逼疯Windows 要WSAStartupLinux 直接socket()Windows 的closesocket到 Linux 变成close阻塞和非阻塞的默认行为也不一样。QFTP 把这些差异用一层薄薄的封装抹平了你拿到的是一套可以直接嵌入自己项目的传输模块而不是一个只能看不能改的玩具。适合谁用如果你在做嵌入式 Linux 设备的数据回传、工控机的日志同步、或者 Windows 服务端和 Linux 采集端之间的文件搬运这份源码能省掉你至少一周的跨平台适配时间。它不依赖 Qt 框架虽然名字带 Q但实际是轻量级实现编译出来就是一个静态库或几个源文件塞进现有工程就能用。下面我从代码结构、编译方式、参数配置到实际踩坑一步步拆给你看。2. 源码结构与跨平台适配层先看懂再动手2.1 目录布局与核心类职责拿到源码包后先别急着make。花十分钟把目录结构过一遍后面改代码时能少走很多弯路。典型的 QFTP 源码包结构是这样的qftp/ ├── include/ │ ├── qftp.h # 对外暴露的接口声明 │ ├── qftpsocket.h # Socket 封装层 │ └── qftpsession.h # 会话管理 ├── src/ │ ├── qftp.cpp # 主逻辑实现 │ ├── qftpsocket.cpp # 跨平台 Socket 适配 │ ├── qftpsession.cpp # 命令解析与状态机 │ └── qftputils.cpp # 字符串、路径处理工具 ├── examples/ │ ├── client_demo.cpp │ └── server_demo.cpp ├── CMakeLists.txt └── README.md核心类就三个QFtpSocket负责所有和系统 Socket API 打交道的事QFtpSession维护单个连接的状态机登录、切换目录、传输模式QFtp是对外门面你调它的connectToHost、login、get、put就行。这种分层的好处是如果你要换底层网络库比如换成 libuv 或 asio只需要动QFtpSocket一个文件。QFtpSocket里的跨平台适配是重点。Windows 下需要#include winsock2.h并链接ws2_32.libLinux 下则是sys/socket.h和netinet/in.h。源码里用#ifdef _WIN32做了条件编译把SOCKET类型、INVALID_SOCKET、SOCKET_ERROR这些差异统一成了自定义的qftp_socket_t和错误码。你拿到代码后第一件事就是确认这个适配层有没有漏掉你目标平台的宏定义。2.2 编译前的环境检查与依赖确认在 Linux 上编译你需要 g 7 以上或 clang 6 以上CMake 3.10 以上。Windows 上推荐用 Visual Studio 2019 或 MinGW-w64。先跑一遍环境检查命令# Linux 下检查编译器和 CMake 版本 g --version cmake --version # Windows 下如果用 MinGW检查 g 是否在 PATH 里 g --version如果版本不够Linux 下用sudo apt install build-essential cmake补齐Windows 下装个 MSYS2 或者直接上 VS 的“使用 C 的桌面开发”工作负载。注意Windows 下如果用 VS 编译CMake 生成工程时要指定-G Visual Studio 16 2019否则默认可能找到 MinGW 的 Makefile 生成器后面链接ws2_32.lib会出问题。依赖方面QFTP 本身不依赖 OpenSSL除非你要做 FTPS也不依赖 zlib。但如果你要传二进制文件建议在编译时打开QFTP_BINARY_MODE宏否则 Windows 下文本模式会把\r\n转成\n传过去的文件大小对不上。这个坑我后面会细说。2.3 用 CMake 生成双端构建脚本源码包里的CMakeLists.txt已经写好了跨平台逻辑但有几个开关你需要根据实际情况调整。打开文件找到这几行option(QFTP_BUILD_EXAMPLES Build example client and server ON) option(QFTP_ENABLE_SSL Enable FTPS support OFF) option(QFTP_STATIC_LIB Build as static library ON)如果你只是想把 QFTP 嵌到现有工程里把QFTP_BUILD_EXAMPLES关掉QFTP_STATIC_LIB打开编译出来就是一个.a或.lib。然后在你自己的CMakeLists.txt里加add_subdirectory(qftp) target_link_libraries(your_target PRIVATE qftp)Windows 下还需要额外链接系统库if(WIN32) target_link_libraries(qftp PRIVATE ws2_32) endif()Linux 下则不需要额外链接因为 Socket 函数在 libc 里。生成构建系统时Linux 用cmake -B build -DCMAKE_BUILD_TYPEReleaseWindows 用cmake -B build -G Visual Studio 16 2019 -A x64。生成完再cmake --build build --config Release两端都能得到可执行文件和库文件。注意Windows 下如果报error: start the windows daemon from a non-elevated terminal之类的权限错误大概率是你把服务端 demo 当成系统服务跑了。QFTP 的服务端 demo 是普通控制台程序直接双击或从命令行启动即可不需要管理员权限。3. 核心接口调用与参数配置从连接建立到文件传输3.1 建立连接与登录的超时参数QFTP 的连接建立分两步先connectToHost再login。这两个操作都有超时参数默认值分别是 30 秒和 10 秒。在实际项目中我一般会把连接超时调到 5 秒登录超时调到 3 秒因为内网环境下超过这个时间基本就是网络不通或服务没起来没必要干等。#include qftp.h QFtp ftp; ftp.setConnectTimeout(5000); // 连接超时 5 秒 ftp.setLoginTimeout(3000); // 登录超时 3 秒 ftp.setTransferTimeout(30000); // 数据传输超时 30 秒 if (!ftp.connectToHost(192.168.1.100, 21)) { // 连接失败getLastError() 返回错误码 printf(connect failed: %d\n, ftp.getLastError()); return -1; } if (!ftp.login(anonymous, anonymousexample.com)) { printf(login failed: %d\n, ftp.getLastError()); return -1; }setConnectTimeout控制的是 TCP 三次握手的时间底层用select或poll实现非阻塞连接。setLoginTimeout控制的是发送 USER/PASS 命令后等待 230 响应的时间。setTransferTimeout是每次send或recv的等待时间传大文件时可以适当调大但不要超过 60 秒否则网络断了你也不知道。3.2 主动模式与被动模式的选择逻辑FTP 有两种数据连接模式PORT主动和 PASV被动。QFTP 默认用 PASV因为主动模式在客户端有防火墙时基本不可用。但如果你在纯内网环境且服务端在 NAT 后面主动模式反而更稳定。ftp.setPassiveMode(true); // 默认就是 true显式写出来方便阅读 // 如果要用主动模式 ftp.setPassiveMode(false); ftp.setLocalDataPort(0); // 0 表示让系统自动分配端口被动模式下客户端发送 PASV 命令服务端返回一个 IP 和端口客户端主动去连这个端口。主动模式下客户端发送 PORT 命令告诉服务端自己的 IP 和端口服务端反过来连客户端。常见坑是被动模式下服务端返回的是内网 IP客户端在外网就连不上。这时候要么让服务端配置公网 IP要么改用主动模式。QFTP 的setPassiveMode可以在每次传输前动态切换你可以根据网络环境写个探测逻辑。3.3 文件上传下载的完整代码示例下面是一个完整的下载示例包含断点续传的判断逻辑#include qftp.h #include sys/stat.h bool downloadFile(QFtp ftp, const std::string remotePath, const std::string localPath) { // 检查本地文件是否存在决定是否续传 struct stat st; long long offset 0; if (stat(localPath.c_str(), st) 0) { offset st.st_size; } // 设置传输类型为二进制避免 Windows 下换行符转换 ftp.setTransferType(QFtp::Binary); // 打开本地文件追加模式 FILE *fp fopen(localPath.c_str(), offset 0 ? ab : wb); if (!fp) { printf(open local file failed\n); return false; } // 如果 offset 0发送 REST 命令告诉服务端从哪个字节开始传 if (offset 0) { if (!ftp.sendRest(offset)) { printf(REST command failed\n); fclose(fp); return false; } } // 开始下载回调里写文件 bool ok ftp.get(remotePath, [fp](const char *data, int len) { fwrite(data, 1, len, fp); }); fclose(fp); return ok; }setTransferType(QFtp::Binary)这行必须加否则 Windows 下默认是 ASCII 模式传过去的二进制文件会被改坏。sendRest是断点续传的关键它发送REST命令给服务端服务端收到后会把文件指针移到指定位置。注意不是所有 FTP 服务端都支持REST如果返回 502 错误就只能从头传。回调函数里的data和len是本次收到的数据块你直接写文件就行QFTP 内部已经处理了粘包和分包。上传的逻辑类似用ftp.put(localPath, remotePath)但要注意权限问题。如果服务端返回 550 Permission denied检查目标目录的写权限以及登录用户是否有上传权限。4. 避坑与常见问题排查血泪经验换来的五条记录4.1 现象Windows 下编译报错“无法解析的外部符号 __imp__WSAStartup”原因没有链接ws2_32.lib。QFTP 的QFtpSocket在 Windows 下会调用WSAStartup和WSACleanup这两个函数在ws2_32.lib里。CMake 里虽然写了target_link_libraries(qftp PRIVATE ws2_32)但如果你是用 VS 手动建工程很容易漏掉。解决在 VS 的“链接器 → 输入 → 附加依赖项”里加上ws2_32.lib。或者直接在代码里加#pragma comment(lib, ws2_32.lib)这样就不用改工程配置了。4.2 现象Linux 下传输大文件时程序卡死CPU 占用率飙升原因QFtpSocket::recv在非阻塞模式下返回EAGAIN时代码里写了个while(true)循环反复重试没有让出 CPU。这是很多手写 Socket 封装的通病。解决找到qftpsocket.cpp里的recvData函数把忙等待改成select或poll等待可读事件。QFTP 源码里其实已经提供了waitForReadyRead方法你只需要在EAGAIN时调用它而不是空转。修改后 CPU 占用会从 100% 降到 1% 以下。4.3 现象被动模式下连接数据端口超时但控制连接正常原因服务端返回的 PASV 响应里IP 地址是内网地址比如 10.0.0.5而客户端在外网根本路由不到这个地址。这是 FTP 协议的历史遗留问题NAT 环境下很常见。解决两个方案。一是让服务端配置pasv_address为公网 IPvsftpd 里是pasv_address公网IP。二是在 QFTP 里忽略 PASV 返回的 IP直接用控制连接的 IP 加返回的端口。QFTP 提供了setIgnorePasvAddress(true)接口打开后就会用控制连接的地址去连数据端口。4.4 现象传输后的文件 MD5 对不上大小差了几个字节原因Windows 下默认用了 ASCII 传输模式\r\n被转换成了\n或者反过来。文本文件可能看不出来但二进制文件比如 zip、exe一传就坏。解决在每次get或put之前显式调用ftp.setTransferType(QFtp::Binary)。不要依赖默认值因为不同 FTP 服务端的默认模式可能不一样。我一般会在login成功后立刻设置一次后面就不管了。4.5 现象程序退出时在 Windows 下报内存泄漏Linux 下正常原因Windows 下WSAStartup和WSACleanup必须成对调用。QFTP 的QFtpSocket构造函数里调了WSAStartup但析构函数里如果提前return了WSACleanup就不会执行。Linux 下没有这个配对要求所以看不出问题。解决检查QFtpSocket的析构函数确保所有路径都会走到WSACleanup。更稳妥的做法是用 RAII把WSAStartup和WSACleanup封装到一个WsaInitializer类里在main函数开头构造结尾自动析构。5. 进阶技巧用 QFTP 做自动化文件同步与校验5.1 基于时间戳的增量同步策略实际项目中我很少直接调get和put传单个文件而是写一个同步器根据本地和服务端的文件修改时间决定传哪些。QFTP 提供了list命令获取远程目录列表返回的每一行包含权限、大小、日期和文件名。解析这个列表就能拿到远程文件的修改时间。// 获取远程目录列表并解析 std::vectorRemoteFile files; ftp.list(/data, [files](const std::string line) { // 典型行格式-rw-r--r-- 1 user group 1024 Jan 15 10:30 data.log RemoteFile rf; char dateBuf[32]; if (sscanf(line.c_str(), %*s %*d %*s %*s %lld %s %*s %s, rf.size, dateBuf, rf.name) 3) { // 解析日期这里简化处理实际要用 strptime files.push_back(rf); } });拿到远程文件列表后和本地stat的结果对比只传修改时间更新的文件。这样每次同步可能只传几个文件而不是整个目录。注意list返回的日期格式取决于服务端有的用Jan 15 10:30有的用2024-01-15 10:30解析时要兼容。5.2 传输后的完整性校验传完文件后怎么确认没传坏最可靠的方法是对比 MD5。但 FTP 协议本身不提供 MD5 命令你需要自己算。我的做法是传完后在服务端执行md5sum命令通过SITE命令或 SSH把结果和本地算的对比。如果服务端不支持就对比文件大小和最后修改时间虽然不如 MD5 严格但能拦住大部分问题。// 本地算 MD5简化示例实际用 OpenSSL 或自己实现 std::string localMd5 computeMd5(localPath); // 通过 SITE 命令让服务端算 MD5需要服务端支持 std::string remoteMd5; ftp.site(MD5 remotePath, [remoteMd5](const std::string resp) { remoteMd5 resp; }); if (localMd5 ! remoteMd5) { printf(MD5 mismatch! local%s remote%s\n, localMd5.c_str(), remoteMd5.c_str()); // 重传或报错 }如果服务端不支持SITE MD5退而求其次对比文件大小。QFTP 的size命令可以获取远程文件大小和本地stat的结果比一下差一个字节都说明有问题。5.3 断线重连与传输恢复网络不稳定时传输中途断开是常事。QFTP 本身没有自动重连你需要在回调里检测错误码然后重新connectToHost、login、sendRest、继续传。我一般会写一个retryTransfer函数最多重试 3 次每次间隔 5 秒。bool retryDownload(QFtp ftp, const std::string remote, const std::string local, int maxRetry) { for (int i 0; i maxRetry; i) { if (downloadFile(ftp, remote, local)) { return true; } printf(download failed, retry %d/%d\n, i 1, maxRetry); sleep(5); // 重新连接 ftp.disconnect(); ftp.connectToHost(192.168.1.100, 21); ftp.login(user, pass); } return false; }注意重连后sendRest的 offset 要重新从本地文件大小算因为上次可能已经传了一部分。这个逻辑在downloadFile里已经处理了只要本地文件是追加模式打开的重试时会自动从断点继续。从那以后我每次传完文件都强制走一遍 MD5 校验哪怕多花几秒钟也比事后发现文件坏了强。希望帮到你。本文还有配套的精品资源点击获取