简介：这是一套基于 Qt 的打印日志系统源码，面向需要为桌面应用搭建日志模块的 Qt 开发者与调试人员，解决默认打印信息难以留存、查看与远程收集的问题。核心思路是借助 qInstallMessageHandler 接管 Qt 消息处理，实现日志文件保存、过期自动删除、窗口实时显示以及网络传输等能力，适合作为项目调试基础设施直接集成。资源包共 17 个文件，约 15KB，包含 6 个 cpp 与 5 个 h 源文件承载日志核心逻辑与配置管理，3 个 ui 文件对应日志窗口与配置界面，另有 pro 工程文件及用户配置，结构紧凑、模块划分清晰。目前已有 6506 人学习下载，说明其在 Qt 日志场景中具备一定参考价值。读者可从中获得一套可运行的日志处理框架，理解消息拦截、分级输出、界面刷新与网络上报的衔接方式，并据此扩展过期清理策略或对接自有服务端，快速补齐项目的日志能力。

1. 日志三件套：本地落盘、窗口刷新、网络上报，Qt 里怎么一次做对

很多 Qt 项目一开始都是qDebug()满天飞，控制台一关日志就没了，线上出问题只能靠用户口述“点了两下就闪退”。我接手过一个模拟项目，现场设备跑了两周，客户说“偶尔卡死”，我们连卡在哪一步都不知道——因为日志只输出到 stdout，而程序是双击启动的，根本没有控制台。后来补上日志系统，才发现是某个串口回调里反复打开文件句柄没释放。这件事让我彻底改掉了“先写业务再补日志”的习惯。

标题里的三件事——打印日志保存、窗口显示日志、网络传输日志——本质上是同一份日志数据的三个出口：文件、UI、网络。难点不在“写日志”，而在多线程安全、UI 不卡顿、网络不阻塞主流程。这篇笔记就按这个思路，把选型、实现、参数和踩过的坑讲清楚，适合正在用 Qt 做上位机、工控界面或跨平台工具的同学。

2. 日志系统架构：为什么不能直接在主线程里写文件

2.1 三个出口的职责边界

先把职责拆开，不然后面一定乱。日志的产生点可能在任何线程：UI 线程、串口线程、网络线程、定时器线程。如果每个产生点都直接QFile::write()，会出现两个问题：一是文件句柄竞争，二是磁盘 IO 抖动直接卡住 UI。

常见做法是引入一个日志中枢，所有线程只负责把日志消息投递进去，由中枢决定什么时候写文件、什么时候发信号给窗口、什么时候打包发网络。这样产生点和消费点解耦，后面加过滤、加级别、加异步都容易。

2.2 用 qInstallMessageHandler 接管 Qt 原生日志

Qt 自带qDebug、qWarning、qCritical，最省事的入口是qInstallMessageHandler。它能把所有 Qt 内部日志也一并接管，包括 Qt 自己打的警告。

// loghandler.cpp #include <QFile> #include <QTextStream> #include <QDateTime> #include <QMutex> static QMutex g_fileMutex; static QFile g_logFile; void customMessageHandler(QtMsgType type, const QMessageLogContext &context, 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_fileMutex); if (g_logFile.isOpen()) { QTextStream ts(&g_logFile); ts << text << "\n"; ts.flush(); } } // 3. 投递到日志中枢（下一节展开） LogHub::instance()->post(text, type); }

逻辑说明：qInstallMessageHandler是全局钩子，安装后所有qDebug()都会走到这里。文件写入用QMutex保护，因为可能多个线程同时打日志。ts.flush()保证崩溃时最后几条不丢，但会牺牲一点性能，后面会讲怎么权衡。

参数说明：时间格式yyyy-MM-dd hh:mm:ss.zzz里的zzz是毫秒，排查时序问题必须带。级别字符串建议固定宽度，方便后续用脚本解析。

2.3 日志中枢：一个线程安全的队列

中枢的核心是一个加锁队列加一个消费者。产生线程只做入队，消费者线程做实际的文件写入和网络发送。

// loghub.h class LogHub : public QObject { Q_OBJECT public: static LogHub *instance(); void post(const QString &text, QtMsgType type); signals: void newLog(const QString &text); // 给窗口用 void logForNetwork(const QString &text); // 给网络模块用 private slots: void onFlushTimer(); private: LogHub(); QQueue<QPair<QString, QtMsgType>> m_queue; QMutex m_mutex; QTimer *m_flushTimer; };

逻辑说明：post()里只做m_mutex.lock()+enqueue+unlock，耗时在微秒级，不会阻塞产生线程。真正的写文件和发网络由定时器批量处理。

参数说明：m_flushTimer间隔建议 200 到 500 毫秒。太短会频繁唤醒，太长会导致窗口日志延迟明显。我一般用 300 毫秒，体感上“实时”和“省资源”比较平衡。

3. 窗口显示日志：QTextEdit 卡死和 QListView 刷屏怎么选

3.1 两种控件的性能分水岭

新手最容易踩的坑是直接往QTextEdit里append()，日志一多界面直接卡成幻灯片。原因是QTextEdit每次 append 都会触发重新布局和重绘，几千行以后就撑不住了。

我的经验是：日志量小于 5000 行、只做展示不做交互，用 QTextEdit；日志量大、需要按级别过滤或搜索，用 QListView + 自定义模型。后者只渲染可见区域，几万行也不卡。

// logwindow.cpp void LogWindow::onNewLog(const QString &text) { // QTextEdit 方案：限制最大块数，防止无限增长 QTextCursor cursor = m_textEdit->textCursor(); cursor.movePosition(QTextCursor::End); m_textEdit->setTextCursor(cursor); m_textEdit->append(text); // 关键：超过阈值就删掉最前面的块 if (m_textEdit->document()->blockCount() > 5000) { QTextCursor delCursor(m_textEdit->document()->firstBlock()); delCursor.movePosition(QTextCursor::NextBlock, QTextCursor::KeepAnchor, 1000); delCursor.removeSelectedText(); } }

逻辑说明：blockCount()是段落数，不是字符数。超过 5000 段就删掉前 1000 段，保持内存和渲染压力可控。movePosition到End是为了让视图自动滚动到底部。

参数说明：5000 和 1000 这两个数可以调。如果日志行特别长，比如带 JSON，建议降到 2000 和 500。删除操作本身有开销，不要每来一条就删，可以每 100 条检查一次。

3.2 跨线程更新 UI 的正确姿势

日志中枢在消费者线程里发信号，窗口对象在主线程。Qt 的信号槽默认是AutoConnection，跨线程时会自动变成队列连接，所以只要信号是在非 UI 线程发的，槽函数就会在 UI 线程执行。这一点很多人不放心，手动QMetaObject::invokeMethod反而容易写错。

// 在 LogHub 构造函数里连接 connect(this, &LogHub::newLog, logWindow, &LogWindow::onNewLog, Qt::QueuedConnection); // 显式声明，避免歧义

逻辑说明：Qt::QueuedConnection保证槽函数在接收者所属线程执行。如果接收者是 UI 对象，就在 UI 线程。显式写出来是为了代码审查时一眼能看出跨线程意图。

参数说明：如果日志量极大，队列连接本身也会成为瓶颈，因为每次都要构造QMetaCallEvent。这时候可以考虑在消费者线程里做批量合并，一次发一个QStringList。

3.3 按级别过滤和关键字高亮

窗口显示日志不只是“能看”，还要“能找”。我一般会在窗口顶部放一个QComboBox选级别，一个QLineEdit输关键字。过滤逻辑放在模型层，不要每次过滤都重建控件。

// 过滤逻辑示意 bool LogFilterModel::filterAcceptsRow(int row, const QModelIndex &parent) const { QModelIndex idx = sourceModel()->index(row, 0, parent); QString text = sourceModel()->data(idx).toString(); // 级别过滤 if (m_minLevel > 0 && !text.contains(m_levelTags[m_minLevel])) return false; // 关键字过滤 if (!m_keyword.isEmpty() && !text.contains(m_keyword, Qt::CaseInsensitive)) return false; return true; }

逻辑说明：filterAcceptsRow是QSortFilterProxyModel的标准接口，返回 false 的行不显示。级别用字符串包含判断，简单但够用。关键字用CaseInsensitive，避免用户大小写纠结。

参数说明：m_levelTags是一个字符串数组，比如{"DEBUG", "INFO", "WARN", "ERROR", "FATAL"}。m_minLevel是当前选中的最低级别索引。

4. 网络传输日志：TCP 还是 UDP，断线了怎么办

4.1 传输选型：先问丢一条日志能不能接受

网络传输日志的选型只看一个问题：丢一条日志会不会导致排查失败。如果日志是用于事后审计或计费，必须 TCP；如果只是实时监控大盘，丢几条无所谓，UDP 更简单。

我一般用 TCP，因为日志量通常不大，TCP 的额外开销可以接受，而且不用自己处理乱序和重传。但 TCP 有个坑：断线时write()会返回 -1，如果不管，日志就静默丢了。

// lognetwork.cpp void LogNetwork::sendLog(const QString &text) { if (m_socket->state() != QAbstractSocket::ConnectedState) { // 断线时先缓存，限制缓存条数防止内存爆掉 if (m_pending.size() < 10000) m_pending.enqueue(text); return; } QByteArray data = text.toUtf8() + "\n"; qint64 written = m_socket->write(data); if (written == -1) { m_pending.enqueue(text); } } void LogNetwork::onConnected() { // 重连成功后把缓存补发 while (!m_pending.isEmpty()) { QByteArray data = m_pending.dequeue().toUtf8() + "\n"; m_socket->write(data); } }

逻辑说明：断线时入队缓存，重连后补发。缓存上限 10000 条，超过就丢弃最旧的，防止内存无限增长。write()返回 -1 也要入队，因为可能刚好在状态切换的瞬间。

参数说明：10000 这个数按日志频率算。如果每秒 100 条，10000 条就是 100 秒的断线容忍。如果断线时间可能更长，要么加大缓存，要么落盘到本地文件等重连后补传。

4.2 心跳和重连：别让日志通道变成僵尸

TCP 连接可能因为网络设备超时被静默断开，本地state()还是ConnectedState，但数据已经发不出去了。必须加心跳。

// 心跳定时器 m_heartbeatTimer = new QTimer(this); connect(m_heartbeatTimer, &QTimer::timeout, this, [this]() { if (m_socket->state() == QAbstractSocket::ConnectedState) { m_socket->write("PING\n"); } else { m_socket->abort(); m_socket->connectToHost(m_host, m_port); } }); m_heartbeatTimer->start(5000); // 5 秒一次

逻辑说明：心跳包用固定字符串PING，服务端收到后可以忽略或回PONG。如果状态不是 Connected，就主动 abort 再重连。abort()会立即关闭 socket，比disconnectFromHost()更果断。

参数说明：心跳间隔 5 秒适合局域网。如果是公网或弱网，可以降到 3 秒，但会增加流量。重连不要立即重试，最好加个退避，比如失败后等 2 秒、4 秒、8 秒。

4.3 日志格式：JSON 还是纯文本

网络传输的日志格式决定了服务端解析的难度。纯文本简单，但字段一多就难解析。JSON 通用，但每条都带花括号和引号，流量会大 30% 左右。

我的折中方案是：本地文件用纯文本，网络传输用 JSON。本地文件给人看，纯文本最舒服；网络传输给程序解析，JSON 最稳。

QJsonObject obj; obj["ts"] = QDateTime::currentMSecsSinceEpoch(); obj["level"] = level; obj["msg"] = msg; obj["thread"] = (quintptr)QThread::currentThreadId(); QJsonDocument doc(obj); QByteArray data = doc.toJson(QJsonDocument::Compact) + "\n";

逻辑说明：toJson(Compact)去掉多余空格，减小体积。thread字段用线程 ID 的整数形式，方便服务端按线程聚合。时间戳用毫秒整数，避免时区和格式问题。

参数说明：如果日志里有二进制或特殊字符，QJsonDocument会自动转义，不用手动处理。但要注意msg太长时 JSON 解析会慢，建议单条日志限制在 4KB 以内。

5. 避坑与排查：日志系统最常见的五个翻车现场

5.1 现象：程序退出时最后几条日志丢失

原因：QTextStream有缓冲区，程序return时没有 flush，缓冲区里的内容随进程一起没了。

解决：在main()里注册qAddPostRoutine或者在QCoreApplication::aboutToQuit信号里手动 flush 并关闭文件。更稳妥的做法是每条日志都 flush，但性能会下降。我一般用定时器每 300 毫秒 flush 一次，退出时再强制 flush 一次。

5.2 现象：窗口日志滚动时界面卡顿

原因：QTextEdit::append()触发了全文重新布局，日志越多越慢。

解决：改用QListView+QAbstractListModel，只渲染可见行。如果必须用QTextEdit，就限制最大块数，并且不要在append后立即调用repaint()。

5.3 现象：网络线程和文件线程同时写同一个日志文件，文件内容错乱

原因：多个线程直接操作QFile，没有加锁，写入位置互相覆盖。

解决：所有文件写入收敛到日志中枢的消费者线程，其他线程只入队。如果确实需要多线程写，用QMutex保护，并且每次写入前seek到文件末尾。

5.4 现象：日志文件无限增长，磁盘被占满

原因：只写不删，没有滚动策略。

解决：按大小或按天滚动。按大小就是超过 10MB 就重命名并新建；按天就是每天零点切换文件。我一般用按天 + 保留 7 天，实现简单，排查时也好找。

// 按天滚动的文件名生成 QString LogFileManager::currentLogPath() const { QString date = QDate::currentDate().toString("yyyyMMdd"); return QString("%1/log_%2.txt").arg(m_logDir).arg(date); }

逻辑说明：每天第一次写日志时检查文件名是否变化，变了就关闭旧文件、打开新文件。清理旧文件可以在启动时做，删除 7 天前的。

参数说明：m_logDir建议放在QStandardPaths::AppDataLocation下，避免权限问题。保留天数按磁盘大小定，一般 7 到 30 天。

5.5 现象：跨线程发信号导致程序崩溃

原因：在非 UI 线程里直接操作 UI 对象，或者信号槽连接类型写成了DirectConnection。

解决：所有 UI 更新必须通过队列连接。如果拿不准当前线程，用QThread::currentThread() == qApp->thread()判断，不是 UI 线程就发信号。

6. 进阶技巧：让日志系统从“能用”到“好用”

6.1 用环境变量控制日志级别，不改代码就能调

线上排查时最怕“日志不够”，但平时又不想打太多。我的做法是用环境变量APP_LOG_LEVEL控制最低级别，默认INFO，需要时设成DEBUG重启即可。

QtMsgType g_minLevel = QtInfoMsg; void initLogLevel() { QByteArray env = qgetenv("APP_LOG_LEVEL"); if (env == "DEBUG") g_minLevel = QtDebugMsg; else if (env == "WARN") g_minLevel = QtWarningMsg; else if (env == "ERROR") g_minLevel = QtCriticalMsg; } // 在 handler 里过滤 if (type < g_minLevel) return;

逻辑说明：qgetenv读取环境变量，不依赖配置文件。type是枚举，数值越小级别越低，所以type < g_minLevel就跳过。

参数说明：环境变量在 Windows 上用set APP_LOG_LEVEL=DEBUG，Linux 上用export APP_LOG_LEVEL=DEBUG。注意qgetenv返回QByteArray，比较时用字符串。

6.2 日志文件加密：只加密敏感字段，不加密全文

有些场景日志里会带设备序列号或用户标识，不能明文落盘。全文加密会导致排查时还要解密，很麻烦。我的做法是只对敏感字段做异或或 AES，其他保持明文。

QString maskSensitive(const QString &input) { // 简单掩码：只保留前 4 位和后 4 位 if (input.length() <= 8) return "****"; return input.left(4) + "****" + input.right(4); }

逻辑说明：掩码比加密更轻量，适合不需要还原的场景。如果必须还原，就用QAESEncryption之类的库做 AES，密钥从安全存储读取。

参数说明：掩码规则按业务定，关键是不要泄露完整标识。如果日志要上传到服务端，掩码在客户端做，不要依赖服务端脱敏。

6.3 用日志做性能埋点：QElapsedTimer 的最小用法

日志不只是记录错误，还可以记录耗时。我在关键路径前后各打一条日志，中间用QElapsedTimer算差值。

QElapsedTimer timer; timer.start(); // 业务代码 doSomething(); qDebug() << "doSomething cost" << timer.elapsed() << "ms";

逻辑说明：elapsed()返回毫秒数，精度足够大多数场景。如果需要微秒，用nsecsElapsed() / 1000。

参数说明：埋点日志建议单独一个级别或单独一个文件，避免和业务日志混在一起。我一般用qDebug打埋点，然后把APP_LOG_LEVEL设成DEBUG时才输出。

6.4 一个我坚持了多年的习惯

每次新建 Qt 项目，第一件事不是写主界面，而是把日志系统搭好：一个 handler、一个中枢、一个窗口、一个网络模块。四个文件，不到 300 行代码，但后面省下的排查时间至少是这 300 行的几十倍。日志系统不是“有空再补”的东西，它是你半夜被叫起来改 bug 时唯一的后悔药。希望帮到你。

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