1. Qt5 里 QFTP 不再随包发布:源码集成是绕不开的第一步
Qt5 是很多团队做桌面端和工控端时首选的 C++ 代码开发工具,但第一次在 Qt5 工程里写 FTP 上传的人多半会愣住:#include <QFtp> 直接报找不到头文件。QFTP 并没有消失,它只是不再随 Qt5 的 QtNetwork 模块一起发布,想用就得把 qftp.cpp、qftp.h、qurlinfo.cpp、qurlinfo.h 这几个源码文件搬进自己的工程。这不是多此一举,而是 Qt5 集成 QFTP 的默认路径。后面按“放源码→改 .pro→封装 FtpClient→编译排错→跑通传输”的顺序走一遍,每一步都给出可直接抄的配置和代码,也会把链接报错和异步时序的坑提前说清楚。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. Qt5 工程接入 QFTP 源码:四个文件与 .pro 的三处硬配置
2.1 QFTP 源码的文件边界:四个文件谁都不能少
QFTP 不是单个头文件就能用的轻量类。qftp.h 声明 QFtp,qftp.cpp 实现命令队列、状态机和套接字读写;qurlinfo.h 和 qurlinfo.cpp 负责解析 LIST 返回的目录条目,QFtp 的 listInfo 信号携带的就是 QUrlInfo 对象。四个文件之间是硬依赖:qftp.cpp 里会 include qftp.h 和 qurlinfo.h,少了 qurlinfo 相关实现,链接阶段就会报 QUrlInfo 的构造函数或成员函数未定义。
我一般把四个文件放在工程根目录下的 3rdparty/qftp/,而不是直接散在根目录。这样做的好处是 .pro 里用 INCLUDEPATH 指一次路径,业务代码里统一写 #include "qftp.h",后面换工程或抽成公共库时整目录拷走就行。目录结构大致是这样:
bash复制# 工程根目录
ftp_demo/
├── ftp_demo.pro
├── main.cpp
├── ftpclient.h
├── ftpclient.cpp
└── 3rdparty/
└── qftp/
├── qftp.h
├── qftp.cpp
├── qurlinfo.h
└── qurlinfo.cpp
这里有一个容易忽略的前置条件:qftp.h 里的 QFtp 类带 Q_OBJECT 宏,它必须经过 moc 处理,否则编译能过、链接会报 vtable for QFtp 未定义。moc 只处理列在 HEADERS 里的头文件,所以 qftp.h 和 qurlinfo.h 一定要写进 HEADERS,不能只靠 INCLUDEPATH 让编译器找到。
2.2 .pro 里 QT += network 与 SOURCES/HEADERS 的写法
材料里给出的最小 .pro 是这样的,我直接沿用并只补了源码子目录的路径:
pro复制QT += core network
CONFIG += console
TARGET = ftp_demo
INCLUDEPATH += $$PWD/3rdparty/qftp
SOURCES += main.cpp \
ftpclient.cpp \
3rdparty/qftp/qftp.cpp \
3rdparty/qftp/qurlinfo.cpp
HEADERS += ftpclient.h \
3rdparty/qftp/qftp.h \
3rdparty/qftp/qurlinfo.h
QT += core network 是整份配置里最不能省的一行。QFTP 内部用 QTcpSocket 收发数据,用 QNetworkProxy 处理代理设置,这两个类都在 network 模块里;只写 QT += core,编译阶段可能不报错,链接阶段会成片出现 undefined reference to QTcpSocket::... 或 QNetworkProxy::...。CONFIG += console 表示当前是个控制台程序,方便先跑通登录和列目录;如果后面要接界面,把 console 换成 QT += widgets 即可,network 仍然要保留。
SOURCES 里 qftp.cpp 和 qurlinfo.cpp 的路径要写对。放在子目录时,要么像上面这样写相对路径,要么把子目录加进 INCLUDEPATH 后只写文件名。两种写法都行,但不要一半用路径、一半用文件名,后面排错时容易看漏。HEADERS 同样要列全,尤其是 qftp.h——它不进 HEADERS,moc 就不会生成 moc_qftp.cpp,链接阶段报 vtable 或 metaObject 未定义,这个坑在 4.2 节会展开。
2.3 qmake 之后怎么确认 qftp.cpp 真的进了编译
改完 .pro 不要直接点 IDE 的构建按钮,先手动跑一遍 qmake 和 make,看输出里有没有 qftp.o 和 qurlinfo.o。命令不复杂:
bash复制# 在工程根目录执行,确保用的是当前 Qt5 的 qmake
qmake ftp_demo.pro
make -j4
# 正常输出中应出现 qftp.o、qurlinfo.o、ftpclient.o、main.o
qmake 的作用是根据 .pro 重新生成 Makefile,make 再按 Makefile 编译。只改 .pro 不重新 qmake,Makefile 还是旧的,新加的 qftp.cpp 根本不会进编译列表,表现就是“代码明明加了,链接却说 QFtp 未定义”。如果之前构建过,先把旧的 .o 和 moc 文件清掉再 qmake,避免新旧对象文件混在一起。
另一个验证办法是看生成的 Makefile 里有没有 qftp.o 这一项。文本编辑器搜一下 qftp.o,搜不到就说明 .pro 的 SOURCES 没生效,回头检查路径和反斜杠续行。构建目录如果不是源码目录(影子构建),qmake 要在构建目录里跑,且 .pro 里的 $$PWD 指向的是 .pro 所在目录,不是构建目录,这一点在写 INCLUDEPATH 时特别容易搞混。
3. 用 FtpClient 包住 QFTP:login、uploadFile、downloadFile 三个动作落地
3.1 为什么不建议在窗口类里直接 new QFtp
QFtp 是异步命令队列:connectToHost、login、put、get 这些调用只是把命令塞进队列,真正的结果通过 stateChanged、commandFinished、error 信号回来。如果直接在窗口类里 new 一个 QFtp,每个按钮槽函数都要自己判断当前状态、自己记 commandId、自己处理失败提示,代码很快会散成一团。更麻烦的是,上传和下载往往要等登录完成才能发,界面层一旦漏判状态,就会得到“命令返回 false 但不知道错在哪”的黑匣子体验。
封装一个 FtpClient 的价值是把“连接状态”和“当前在做什么”收在一个类里。对外只暴露 login(host, port, user, password)、uploadFile(local, remote)、downloadFile(remote, local) 三个动作,以及 loggedIn、uploadFinished、downloadFinished、progress、errorOccurred 几个信号。界面层只连信号,不碰 QFtp 的 commandId,排错时也只需要看 FtpClient 的状态字段。
3.2 FtpClient 的成员与状态字段
头文件里我保留 QFtp 指针、传输文件指针、当前状态和待处理命令类型。状态字段不是为了好看,而是为了拦住“登录没完成就发上传”这类时序错误:
cpp复制// ftpclient.h
#ifndef FTPCLIENT_H
#define FTPCLIENT_H
#include <QObject>
#include <QString>
class QFtp;
class QFile;
class FtpClient : public QObject
{
Q_OBJECT
public:
explicit FtpClient(QObject *parent = nullptr);
~FtpClient();
void login(const QString &host, quint16 port,
const QString &user, const QString &password);
void uploadFile(const QString &localPath, const QString &remotePath);
void downloadFile(const QString &remotePath, const QString &localPath);
void abort();
signals:
void loggedIn();
void uploadFinished(bool ok, const QString &message);
void downloadFinished(bool ok, const QString &message);
void progress(qint64 done, qint64 total);
void errorOccurred(const QString &message);
private slots:
void onStateChanged(int state);
void onCommandFinished(int id, bool error);
void onError(int errorCode);
private:
enum PendingCommand { Idle, LoggingIn, Uploading, Downloading };
QFtp *m_ftp = nullptr;
QFile *m_file = nullptr;
PendingCommand m_pending = Idle;
int m_loginCommandId = -1;
QString m_lastError;
};
#endif // FTPCLIENT_H
这里把 m_loginCommandId 单独存下来,是因为 commandFinished 只给一个整数 id,不告诉你是哪条命令结束。登录命令的 id 记下来,后面就能在回调里精确判断“这次结束的是不是登录”,而不是靠猜。m_pending 则用于业务层状态判断,uploadFile 进来先看是不是 LoggingIn 或 Idle,不是 LoggedIn 就直接发 errorOccurred 返回。
3.3 登录、上传、下载的代码与信号连接
构造函数里把 QFtp 的信号一次性接好,后面所有动作都走同一套回调:
cpp复制// ftpclient.cpp 片段
FtpClient::FtpClient(QObject *parent) : QObject(parent)
{
m_ftp = new QFtp(this);
connect(m_ftp, &QFtp::stateChanged,
this, &FtpClient::onStateChanged);
connect(m_ftp, &QFtp::commandFinished,
this, &FtpClient::onCommandFinished);
connect(m_ftp, &QFtp::error,
this, &FtpClient::onError);
connect(m_ftp, &QFtp::dataTransferProgress,
this, &FtpClient::progress);
}
void FtpClient::login(const QString &host, quint16 port,
const QString &user, const QString &password)
{
if (m_pending != Idle) {
emit errorOccurred(QStringLiteral("上一条命令还没结束"));
return;
}
m_pending = LoggingIn;
m_ftp->connectToHost(host, port);
// 登录动作放在 stateChanged 的 Connected 分支里发,
// 避免 connectToHost 还没完成就 login
}
connectToHost 之后不能立刻 login,要等 stateChanged 走到 QFtp::Connected 再发登录命令。这是 QFTP 异步队列的基本节奏,材料里虽然没有展开,但 stateChanged 信号本身就是为这个节奏准备的。登录命令的 id 在 login 调用后立即保存:
cpp复制void FtpClient::onStateChanged(int state)
{
if (state == QFtp::Connected && m_pending == LoggingIn) {
m_loginCommandId = m_ftp->login(m_user, m_password);
} else if (state == QFtp::LoggedIn) {
m_pending = Idle;
emit loggedIn();
}
}
上传和下载的入口都先做状态检查,再打开 QFile。QFtp::put(QIODevice *, const QString &, TransferType) 会从设备里读数据,设备必须保持打开,所以文件指针用成员变量保存,完成回调里再 close 和 deleteLater:
cpp复制void FtpClient::uploadFile(const QString &localPath,
const QString &remotePath)
{
if (m_pending != Idle) {
emit errorOccurred(QStringLiteral("当前有命令在执行"));
return;
}
m_file = new QFile(localPath, this);
if (!m_file->open(QIODevice::ReadOnly)) {
emit uploadFinished(false, m_file->errorString());
m_file->deleteLater();
m_file = nullptr;
return;
}
m_pending = Uploading;
m_ftp->put(m_file, remotePath, QFtp::Binary);
}
下载方向相反,QFile 以只写方式打开,get(remotePath, m_file, QFtp::Binary) 把远端数据写进本地文件。完成判断统一放在 onCommandFinished 里,根据 m_pending 决定发哪个完成信号,并把 error 参数和 m_lastError 一起带出去。这样界面层拿到的就是“成功/失败 + 原因”,不用再自己去翻 QFtp 的错误码。
3.4 命令队列:避免异步命令互相踩踏
QFtp 自己内部有命令队列,但应用层不能把它当成同步接口用。最常见的误用是 login() 刚调用完就 uploadFile(),两个命令前后脚进队列,第二个命令在服务器还没完成认证时就发出去,返回 false。FtpClient 里用 m_pending 拦住这种调用:登录期间 m_pending 是 LoggingIn,上传入口直接拒绝;只有 stateChanged 走到 LoggedIn 才把 m_pending 置回 Idle。
另一个细节是 commandFinished 的 id 匹配。如果登录命令失败,m_loginCommandId 对应的回调会带 error = true,此时要把 m_pending 复位并发出 errorOccurred,而不是继续等 LoggedIn。下面这段是 onCommandFinished 的核心逻辑:
cpp复制void FtpClient::onCommandFinished(int id, bool error)
{
if (id == m_loginCommandId) {
m_loginCommandId = -1;
if (error) {
m_pending = Idle;
emit errorOccurred(m_lastError.isEmpty()
? QStringLiteral("登录失败")
: m_lastError);
}
return;
}
if (m_pending == Uploading || m_pending == Downloading) {
const bool isUpload = (m_pending == Uploading);
m_pending = Idle;
if (m_file) {
m_file->close();
m_file->deleteLater();
m_file = nullptr;
}
if (isUpload)
emit uploadFinished(!error, m_lastError);
else
emit downloadFinished(!error, m_lastError);
}
}
这段代码不复杂,但它把“命令 id 对应哪件事”和“文件句柄什么时候释放”绑在一起,避免了两个常见问题:一是登录失败后状态卡在 LoggingIn,后面所有上传都被自己拦住;二是传输结束后 QFile 没关,Windows 下文件被占用,下一次覆盖写直接失败。
4. Qt5 集成 QFTP 的编译与链接排错:四条高频翻车记录
4.1 链接报 undefined reference:先看 network 模块有没有进 .pro
现象:编译阶段一切正常,链接时出现成片的 undefined reference to 'QTcpSocket::...'、undefined reference to 'QNetworkProxy::...',或者 QFtp::connectToHost 里引用的套接字符号找不到。
原因:QFTP 的源码直接依赖 QtNetwork 模块里的 QTcpSocket 和 QNetworkProxy。.pro 里只写了 QT += core,编译器能找到头文件(因为 QFtp 源码自己 include 了 QtNetwork 的头),但链接器没有把 QtNetwork 库链进来。
解决:把 .pro 第一行改成 QT += core network,然后清理构建目录,重新 qmake 和 make。只改 .pro 不重新 qmake 是无效的,Makefile 里的链接参数不会自己更新:
bash复制# 清理旧的构建产物,避免旧 Makefile 干扰
make clean
qmake ftp_demo.pro
make -j4
如果用的是影子构建,make clean 要在构建目录里执行;如果构建目录里还有旧的 qftp.o,先把整个构建目录删掉再 qmake 更稳妥。
4.2 找不到 qftp.h 或 moc 不生成:HEADERS 和 INCLUDEPATH 要同时对
现象:一种是编译报 fatal error: qftp.h: No such file or directory;另一种更隐蔽,编译能过,链接报 undefined reference to 'QFtp::metaObject() const' 或 vtable for QFtp 未定义。
原因:前者是源码放在子目录但 .pro 里没加 INCLUDEPATH,或者 SOURCES/HEADERS 里的相对路径写错。后者是 qftp.h 没有列进 HEADERS,moc 没有处理带 Q_OBJECT 的 QFtp 类,缺少 moc_qftp.cpp 里的元对象实现。
解决:INCLUDEPATH 和 HEADERS 同时检查。源码在 3rdparty/qftp/ 时,.pro 里要有 INCLUDEPATH += $$PWD/3rdparty/qftp,HEADERS 里要有 3rdparty/qftp/qftp.h 和 3rdparty/qftp/qurlinfo.h。改完重新 qmake,构建输出里应该能看到 moc_qftp.cpp 被编译。如果 HEADERS 写的是文件名但文件在子目录,moc 找不到文件,同样不会生成。
4.3 重复定义:qftp.cpp 被编了两次
现象:链接报 multiple definition of 'QFtp::QFtp(QObject*)',或者 multiple definition of 'QFtp::staticMetaObject'。
原因:SOURCES 里已经列了 qftp.cpp,业务代码里又写了 #include "qftp.cpp";或者工程里有两份 qftp.cpp(比如从两个旧工程各拷了一份),两份都被编进了 SOURCES。QFtp 的构造函数和静态元对象只能有一份实现。
解决:业务代码只 include qftp.h,绝不 include qftp.cpp。检查 .pro 的 SOURCES,确保 qftp.cpp 和 qurlinfo.cpp 各只出现一次。如果工程里确实有两份源码,删掉多余的那份,保留 3rdparty/qftp/ 下的唯一副本。下面这种写法是要避免的:
cpp复制// 错误:业务 .cpp 里直接 include 实现文件
#include "3rdparty/qftp/qftp.cpp"
// 正确:只 include 头文件,实现文件交给 SOURCES 编译
#include "qftp.h"
4.4 登录还没完成就发 put:QFtp 是异步的
现象:上传或下载返回 false,错误信息是 QFtp: Cannot write while not connected 或 Not logged in;或者 commandFinished 的 id 跟预期对不上,完成信号发到了错误的命令上。
原因:connectToHost、login、put、get 都是异步命令,调用返回只代表命令入队,不代表服务器已经处理完。登录命令还没完成就发 put,服务器端还没进入登录态,命令自然失败。另一种情况是多个命令同时入队,commandFinished 的 id 交叉,业务层没记 id 就分不清是谁结束。
解决:登录完成前不允许发传输命令。FtpClient 里用 m_pending 做状态闸门,stateChanged 收到 QFtp::LoggedIn 才把状态置回 Idle。如果不想引入封装类,至少在调用 put 前检查 m_ftp->state() == QFtp::LoggedIn,并且把 login 返回的 commandId 存下来,在 commandFinished 里先匹配 id 再处理。登录失败时要把状态复位,否则后面所有命令都会被闸门拦住,看起来像“程序卡死”。
5. 跑通一次完整传输:连接、列目录、上传、下载的参数与时序
5.1 连接与登录:状态信号怎么等
QFtp 的状态枚举把连接过程拆得很细:Unconnected、HostLookup、Connecting、Connected、LoggedIn、Closing。发起 connectToHost(host, port) 后,先到 HostLookup,再到 Connecting,最后到 Connected;此时才能发 login(user, password)。登录成功后状态变成 LoggedIn,失败则回到 Unconnected 并触发 error 信号。
下面这段状态处理可以直接放在 FtpClient 里,重点是“Connected 才登录、LoggedIn 才放行”:
cpp复制void FtpClient::onStateChanged(int state)
{
switch (state) {
case QFtp::HostLookup:
// 正在解析主机名,不做事
break;
case QFtp::Connected:
if (m_pending == LoggingIn)
m_loginCommandId = m_ftp->login(m_user, m_password);
break;
case QFtp::LoggedIn:
m_pending = Idle;
emit loggedIn();
break;
case QFtp::Unconnected:
if (m_pending == LoggingIn) {
m_pending = Idle;
emit errorOccurred(QStringLiteral("连接或登录失败"));
}
break;
default:
break;
}
}
参数上,connectToHost 的端口默认是 21,材料里没写端口时按默认走;如果服务器改了端口,就显式传第二个参数。login 的用户名和密码为空时,QFTP 会发匿名登录,但多数内网 FTP 都要求显式账号,建议不要把空值当默认。超时控制 QFTP 本身没有直接接口,我一般在外层用 QTimer 等 LoggedIn,超过设定时间就调 abort() 并提示,避免界面一直转圈。
5.2 列目录与路径处理
list() 触发后,服务器返回的每个目录条目都会通过 listInfo(const QUrlInfo &) 信号逐个送到,全部结束后再发 commandFinished。所以列目录不能在 list() 返回后立刻读结果,要把条目攒在 QList<QUrlInfo> 里,等 commandFinished 再统一展示。QUrlInfo 的 name() 是文件名,isDir() 判断目录,size() 是字节数,lastModified() 是修改时间。
路径拼接是另一个高频翻车点。FTP 协议只认正斜杠,Windows 下用 QDir::separator() 拼出来的反斜杠路径传到服务器会变成非法文件名。远端路径统一用 / 拼接,本地路径才用 QDir 处理:
cpp复制// 远端路径统一用正斜杠
QString remotePath = baseDir;
if (!remotePath.endsWith(QLatin1Char('/')))
remotePath += QLatin1Char('/');
remotePath += fileName;
// 本地路径用 QDir 拼,兼容 Windows
QString localPath = QDir(localDir).filePath(fileName);
cd() 会改变服务器当前目录,后续的相对路径都基于它。如果不想依赖当前目录,就在 put/get 里直接传完整远端路径,减少状态耦合。列目录时如果远端路径含中文,注意服务器端的编码设置;QFTP
