简介：这是一套基于 Qt 的打印日志系统源码，面向需要为桌面应用搭建调试与运行日志模块的开发者，尤其适合已掌握 Qt 基础、希望深入理解消息处理机制的中级学习者。它围绕 qInstallMessageHandler 自定义消息处理器，解决默认打印信息仅输出到标准输出或调试器、难以留存与远程查看的问题，实现日志文件保存、过期自动删除、窗口实时显示以及网络传输等能力。压缩包共 17 个文件，约 15KB，包含 6 个 cpp 与 5 个 h 源文件承载日志核心逻辑与配置管理，3 个 ui 文件对应日志窗口与配置界面，另有 pro 工程文件及用户配置，结构紧凑、便于直接编译运行。目前已有 6506 人学习下载。读者可从中获得一套可复用的日志处理框架，理解消息分级、文件落盘、过期清理、界面刷新与网络上报的完整链路，并借鉴其模块划分与配置思路，快速移植到自己的 Qt 项目中，减少重复造轮子的时间。
1. 从一次现场调试翻车说起：Qt 日志系统到底该长什么样
上个月帮一个做工业上位机的朋友排查问题，现场设备跑了一周，界面卡死过一次，重启后什么线索都没留下。他问我：“Qt 里 qDebug 打出来的东西，为什么一关程序就没了？”这个问题其实特别典型——很多 Qt 项目在开发阶段靠 qDebug 看输出，一到交付现场就抓瞎，因为控制台输出既不落盘，也没法远程回传。一个能用的 Qt 日志系统，至少要同时解决三件事：日志写进文件、日志显示在窗口、日志通过网络发出去。这三件事听起来简单，但真动手写，你会发现文件切割、线程安全、窗口刷新频率、网络断线重连，每一个都是坑。这份资源就是围绕这三个需求做的一套完整实现，适合正在做 Qt 桌面端或嵌入式上位机的开发者，尤其是那些需要把程序部署到客户现场、又不想每次都跑过去看屏幕的人。它不是什么大框架，就是一套可以直接嵌进现有工程的日志模块，代码量不大，但把该考虑的点基本都覆盖了。
2. 拆开看架构：qInstallMessageHandler 与三条输出链路
2.1 为什么不用 qDebug 直接重定向
Qt 自带的 qDebug、qWarning、qCritical 最终都会走一个叫 message handler 的函数。默认情况下，这个函数把日志写到 stderr，在 Windows 下如果你用 GUI 子系统编译，stderr 根本没人看。Qt 提供了qInstallMessageHandler来替换这个默认行为，这是整个日志系统的入口。很多人第一反应是写个类继承 QObject，然后到处调自己的 log 函数，但那样就丢掉了 Qt 原有日志宏的便利性。正确的做法是：安装一个全局 handler，在里面统一做格式化，然后分发给文件、窗口、网络三个消费者。这样你代码里原来的 qDebug() 一行都不用改，日志自动就落到三个地方去了。
2.2 三条链路的职责划分
文件链路负责持久化，要求是写入快、不丢、能按大小或日期切割。窗口链路负责实时展示，要求是不能因为日志太多把 UI 线程卡死，所以必须做批量刷新和缓冲。网络链路负责远程传输，要求是断线不能影响主程序，所以得放在独立线程里，并且要有重连机制。这三条链路共享同一个格式化后的日志字符串，但各自的消费节奏完全不同。我一般会在 handler 里只做最轻量的格式化，然后把日志丢进一个线程安全的队列，由后台线程去写文件和发网络，窗口那边用定时器批量取。这样即使磁盘 IO 慢或者网络卡，也不会阻塞主线程。
2.3 核心代码骨架
// loghandler.cpp #include <QDateTime> #include <QThread> #include <QFile> #include <QTextStream> #include <QMutex> static QMutex g_logMutex; static QFile g_logFile; static QTextStream g_logStream; void customMessageHandler(QtMsgType type, const QMessageLogContext &ctx, const QString &msg) { // 1. 格式化：时间 + 级别 + 文件行号 + 内容 QString level; switch (type) { case QtDebugMsg: level = "DEBUG"; break; case QtInfoMsg: level = "INFO"; break; case QtWarningMsg: level = "WARN"; break; case QtCriticalMsg: level = "ERROR"; break; case QtFatalMsg: level = "FATAL"; break; } QString text = QString("[%1][%2] %3") .arg(QDateTime::currentDateTime().toString("yyyy-MM-dd hh:mm:ss.zzz")) .arg(level) .arg(msg); // 2. 加锁写入文件，避免多线程交错 QMutexLocker locker(&g_logMutex); if (g_logFile.isOpen()) { g_logStream << text << "\n"; g_logStream.flush(); } // 3. 推送到窗口和网络队列（伪代码，实际用信号槽或队列） LogDispatcher::instance()->enqueue(text); }这段代码的关键点有三个。第一，qInstallMessageHandler(customMessageHandler)要在 main 函数最前面调用，越早越好，否则之前的日志抓不到。第二，文件写入必须加锁，因为 qDebug 可能从多个线程调用，不加锁会出现日志内容交错。第三，g_logStream.flush()每次写都刷新，虽然有点性能损耗，但能保证程序崩溃时日志不丢——这是血泪经验，曾经有个项目因为缓冲区没刷新，崩溃后最后 200 毫秒的日志全没了，正好错过关键错误。
2.4 文件切割策略怎么选
文件不能无限增长，常见做法有两种：按大小切割和按日期切割。按大小切割适合高频日志，比如每 10MB 换一个文件，保留最近 10 个。按日期切割适合低频但需要长期归档的场景，每天一个文件。我一般会做成可配置的，默认按大小切，因为现场调试时你更关心最近的日志，而不是上个月的。切割逻辑放在写文件之前判断：如果当前文件超过阈值，关闭、重命名、开新文件。重命名时加上时间戳，避免覆盖。
void rotateLogFile() { if (g_logFile.size() < MAX_SIZE) return; g_logFile.close(); QString newName = QString("app_%1.log") .arg(QDateTime::currentDateTime().toString("yyyyMMdd_hhmmss")); g_logFile.rename(newName); g_logFile.setFileName("app.log"); g_logFile.open(QIODevice::WriteOnly | QIODevice::Append); g_logStream.setDevice(&g_logFile); }参数 MAX_SIZE 建议设成 5MB 到 20MB 之间，太小会导致文件数量爆炸，太大则单个文件打开慢。保留数量用 QDir 的 entryList 按时间排序后删旧的，别用 QFileInfo 的创建时间，那个在 Linux 下不可靠，用文件名里的时间戳排序最稳。
3. 窗口显示日志：别让 UI 线程被日志拖死
3.1 为什么不能直接在 handler 里更新 QTextEdit
新手最容易犯的错就是在 customMessageHandler 里直接拿到窗口指针，然后ui->textEdit->append(text)。这在单线程测试时没问题，但一旦日志量大，比如每秒几百条，UI 线程就会被 append 的布局计算拖垮，界面直接卡成幻灯片。更严重的是，如果日志来自工作线程，而 QTextEdit 只能在主线程操作，程序会随机崩溃。所以窗口显示必须做两件事：跨线程投递和批量刷新。
3.2 用信号槽做线程安全的投递
正确做法是定义一个 LogDispatcher 类，继承 QObject，在 handler 里通过QMetaObject::invokeMethod或者自定义信号把日志发到主线程。因为 handler 可能在任何线程被调用，而 dispatcher 对象住在主线程，用队列连接（Qt::QueuedConnection）就能自动跨线程。
// logdispatcher.h class LogDispatcher : public QObject { Q_OBJECT public: static LogDispatcher *instance(); void enqueue(const QString &text); // 线程安全，内部加锁 signals: void newLogBatch(const QStringList &lines); // 批量信号 private: QMutex m_mutex; QStringList m_buffer; QTimer *m_flushTimer; };enqueue 里把日志追加到 m_buffer，然后启动一个 100ms 的定时器，定时器超时后把 buffer 里的内容一次性 emit 出去。窗口那边连接 newLogBatch 信号，在槽函数里把 QStringList 拼成一个大字符串，一次 append 到 QTextEdit。这样 UI 线程每 100ms 只做一次 append，而不是每条日志做一次。实测下来，每秒 1000 条日志，界面依然流畅。
3.3 窗口显示的三个实用细节
第一个细节是自动滚动。QTextEdit 的 append 会自动滚到底部，但如果你用了 insertPlainText 就不会。建议用 append，省事。第二个细节是最大行数限制。日志窗口不能无限增长，否则内存会爆。我一般设成 5000 行，超过就删最前面的。QTextEdit 没有直接删行的 API，可以用document()->setMaximumBlockCount(5000)，Qt 会自动帮你删旧的，这个特别方便。第三个细节是级别过滤。窗口上放一个 QComboBox，让用户选“全部 / 只看警告 / 只看错误”。过滤逻辑放在 dispatcher 的 enqueue 之前，或者窗口槽函数里判断都行，但别在 handler 里判断，因为文件那边可能还需要完整日志。
// 窗口槽函数 void MainWindow::onNewLogBatch(const QStringList &lines) { for (const QString &line : lines) { if (m_filterLevel == "WARN" && !line.contains("[WARN]")) continue; if (m_filterLevel == "ERROR" && !line.contains("[ERROR]")) continue; ui->logEdit->append(line); } }注意setMaximumBlockCount要在 append 之前设置一次就行，不用每次设。另外 QTextEdit 在大量文本时 setPlainText 比 append 快，但会丢失滚动位置，所以只在清空时用。
3.4 性能对比：直接 append vs 批量刷新
我做过一个简单测试，在同样的机器上打 10000 条日志。直接 append 每条日志，界面卡顿明显，总耗时约 4.2 秒，期间窗口无响应。用 100ms 批量刷新，总耗时约 0.8 秒，界面全程可交互。差距主要来自 QTextEdit 的布局计算次数，批量刷新把 10000 次布局变成 100 次，自然快得多。所以别偷懒，多写一个 dispatcher 类，后面省心得多。
4. 网络传输日志：断线重连与协议选择
4.1 TCP 还是 UDP
网络传输日志，首先得选协议。TCP 可靠，但断线后需要重连，而且如果服务端没开，客户端会一直重试。UDP 无连接，发出去就不管，适合局域网内广播，但丢包了你也不知道。我一般推荐 TCP，因为日志传输对可靠性要求高于实时性，丢一条关键错误可能就白干了。如果现场网络不稳定，可以在应用层加一个简单的确认机制，但大多数情况下 TCP 自带的确认就够了。端口选择上，别用 80 或 443，容易被占用或拦截，选一个 10000 以上的高位端口，比如 19000。
4.2 独立线程与重连策略
网络发送绝对不能放在主线程，也不能放在文件写入的那个线程，因为网络阻塞时间不可控。我一般会单独开一个 QThread，里面跑一个 QTcpSocket。日志通过队列传进去，线程里循环取队列、写 socket。断线后不要立刻疯狂重连，那样会把 CPU 跑满。常见的做法是退避重连：第一次等 1 秒，第二次 2 秒，第三次 4 秒，最多到 30 秒。这样既不会漏掉恢复时机，也不会给服务端造成压力。
// networkworker.cpp void NetworkWorker::run() { while (!m_stop) { if (m_socket->state() != QAbstractSocket::ConnectedState) { m_socket->connectToHost(m_host, m_port); if (!m_socket->waitForConnected(3000)) { QThread::sleep(m_retryInterval); m_retryInterval = qMin(m_retryInterval * 2, 30); continue; } m_retryInterval = 1; // 重连成功后重置 } QString log = m_queue.dequeue(); // 阻塞取，带超时 if (!log.isEmpty()) { m_socket->write(log.toUtf8() + "\n"); m_socket->flush(); } } }参数说明：waitForConnected(3000)是连接超时 3 秒，别设太长，否则线程卡住无法响应停止信号。m_retryInterval初始 1 秒，翻倍增长，上限 30 秒。队列的 dequeue 要带超时，比如 500ms，这样线程能定期检查 m_stop 标志，退出时不会卡死。
4.3 日志格式与粘包处理
TCP 是字节流，没有消息边界。如果你直接 write 一条日志，服务端可能一次收到半条，或者一次收到三条粘在一起。解决办法很简单：每条日志末尾加换行符\n，服务端按行读取。这是最通用的做法，兼容各种日志收集工具。日志内容本身用 UTF-8 编码，别用本地编码，否则中文会乱码。如果日志里本身可能包含换行，比如异常堆栈，那就需要转义或者用长度前缀。我一般会把日志里的换行替换成\\n字面量，接收端再还原，这样一行就是一条，简单可靠。
4.4 服务端接收的简易实现
服务端可以用 Python 写一个十几行的脚本，监听端口，按行读取，打印到控制台或写入文件。这样你在办公室就能看到现场设备的日志。
# log_server.py import socket HOST = '0.0.0.0' PORT = 19000 with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s: s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) s.bind((HOST, PORT)) s.listen(1) print(f"listening on {PORT}") conn, addr = s.accept() with conn: print(f"connected from {addr}") buffer = b"" while True: data = conn.recv(4096) if not data: break buffer += data while b"\n" in buffer: line, buffer = buffer.split(b"\n", 1) print(line.decode("utf-8", errors="replace"))这个脚本没有做多客户端和断线重连，但作为调试工具足够了。注意errors="replace"防止非法 UTF-8 导致脚本崩溃。生产环境可以用现成的日志服务，但调试阶段这个最轻量。
5. 避坑与排查：那些让我加班到凌晨的细节
5.1 日志文件写入后内容为空
现象：程序运行正常，日志文件也创建了，但打开一看是空的，或者只有几行。原因：QTextStream 有内部缓冲区，不 flush 或者不关闭文件，内容不会立刻落盘。解决：每次写入后调用g_logStream.flush()，或者在 handler 里用g_logFile.write()直接写字节，绕过 QTextStream 的缓冲。我后来改成g_logFile.write(text.toUtf8() + "\n")，简单直接，再也没丢过。
5.2 多线程下日志交错乱码
现象：日志里出现半条中文加半条英文，或者两条日志混在一起。原因：多个线程同时调用 qDebug，handler 里的文件写入没有加锁，两个线程的 write 交错执行。解决：在 handler 里用 QMutexLocker 包住文件写入部分。注意锁的粒度要小，只锁 write 和 flush，格式化部分不用锁，否则会影响并发性能。
5.3 窗口日志导致程序启动变慢
现象：程序启动时，初始化代码里打了几百条 qDebug，窗口还没显示出来就卡住了。原因：handler 在窗口构造之前就被调用，dispatcher 试图往一个还不存在的窗口发信号，或者缓冲区无限增长。解决：dispatcher 在窗口没准备好时只缓存不发送，窗口构造完成后调用一个setReady()把缓存刷过去。另外启动阶段的日志可以只写文件，不推窗口，等窗口显示后再开始推。
5.4 网络线程退出时程序崩溃
现象：关闭程序时，网络线程还在 waitForConnected 或 dequeue 阻塞，主线程直接析构了 socket，导致野指针崩溃。解决：在程序退出前，先设置 m_stop 标志，然后调用m_socket->abort()强制中断阻塞，再thread->quit()和thread->wait(3000)。顺序很重要，先停线程再删对象。我一般会在 main 函数的 aboutToQuit 信号里做这个清理。
5.5 日志级别过滤把文件也过滤了
现象：窗口上选了“只看错误”，结果文件里也只有错误日志了。原因：过滤逻辑写在了 handler 里，把不该过滤的也过滤了。解决：过滤只放在窗口显示层，handler 永远输出完整日志到文件和网络。窗口的过滤条件作为参数传给 dispatcher，dispatcher 在 emit 之前判断，而不是在 enqueue 之前。
6. 进阶技巧：用环境变量控制日志行为与远程动态调级
6.1 环境变量控制日志级别
现场调试时，你不可能重新编译程序来改日志级别。常见做法是读环境变量，比如APP_LOG_LEVEL=DEBUG，程序启动时解析，决定哪些级别的日志进入 handler。Qt 本身支持QT_LOGGING_RULES，但那个只控制 categorized logging，对普通的 qDebug 不生效。所以我在 handler 里加一个全局级别变量，从环境变量初始化。
static int g_minLevel = 0; // 0=DEBUG, 1=INFO, 2=WARN, 3=ERROR void initLogLevel() { QByteArray env = qgetenv("APP_LOG_LEVEL"); if (env == "INFO") g_minLevel = 1; else if (env == "WARN") g_minLevel = 2; else if (env == "ERROR") g_minLevel = 3; else g_minLevel = 0; } void customMessageHandler(QtMsgType type, ...) { int level = 0; switch (type) { case QtDebugMsg: level = 0; break; case QtInfoMsg: level = 1; break; case QtWarningMsg: level = 2; break; case QtCriticalMsg: level = 3; break; case QtFatalMsg: level = 3; break; } if (level < g_minLevel) return; // 低于阈值直接丢弃 // ... 后续格式化与分发 }这样现场人员只需要在启动脚本里改一行set APP_LOG_LEVEL=DEBUG，不用找你重新编译。注意 QtFatalMsg 不能被过滤，因为它会导致程序终止，必须记录。
6.2 远程动态调级
更进一步，你可以让网络链路支持接收指令。服务端发来SET_LEVEL=DEBUG，客户端解析后修改 g_minLevel。这样你在办公室就能远程打开调试日志，抓完再关掉。实现上就是在网络线程里加一个接收分支，收到指令后通过信号槽通知主线程修改全局变量。注意 g_minLevel 要用原子变量或者加锁，因为 handler 可能在多个线程读它。
QAtomicInt g_minLevelAtomic(0); // 网络线程收到指令 if (line.startsWith("SET_LEVEL=")) { QString lv = line.mid(10); int v = (lv == "DEBUG") ? 0 : (lv == "INFO") ? 1 : (lv == "WARN") ? 2 : 3; g_minLevelAtomic.storeRelease(v); }用 QAtomicInt 的 storeRelease 和 loadAcquire 保证多线程可见性，比加锁轻量。这个技巧在排查偶发问题时特别有用，你不需要一直开着 DEBUG 级别把磁盘写满，只在需要的时候远程打开几分钟。
6.3 日志文件轮转的验证方法
写完切割逻辑后，怎么验证它真的在工作？我一般会写一个测试函数，循环打 100000 条日志，然后检查目录下是否生成了多个文件，每个文件大小是否接近阈值，最旧的文件是否被删除。这个测试跑一遍只要几秒钟，但能提前发现切割逻辑的边界问题，比如文件大小刚好等于阈值时是否触发切割、重命名时是否覆盖已有文件。从那以后我每次改日志模块，都强制走一遍这个压力测试，再也不敢凭感觉了。
希望帮到你。
本文还有配套的精品资源，点击获取
