企业官网建设流程全解析

1. 为什么要给 Qt 工程做一套日志宏定义

说实话，刚接触 Qt 那阵子，我调试程序基本都是qDebug()一把梭。哪里不对就扔一句qDebug() << "xxx"，跑起来看控制台输出，看完了再删掉或者注释掉。小工程这么干确实没毛病，但工程一旦上了规模——模块多了、线程多了、跟外部设备打交道频繁了——这套原始打法立刻会反噬你。

最典型的问题是五个：

第一，qDebug()的输出没有任何分级概念。调试信息和错误信息混在一起，全是白字黑底刷屏。关键报错被淹没在成千上万条普通日志里，你 Ctrl+F 都能翻半天。

第二，函数名、行号、时间戳全靠手写。我见过有人写qDebug() << "enter func: " << __FUNCTION__;写了几十处，后来函数改名，这些日志全成了误导信息。

第三，发布版根本不该让调试信息满天飞。客户环境里跑出来一堆英文日志，对方截图发过来你还得猜上下文。

第四，日志无文件化。程序一崩，控制台那点输出跟着窗口一起消失了，事后复盘全靠记忆，这在大项目里几乎是灾难。

第五，跨平台的换行、编码、路径处理问题。Windows 和 Linux 下日志文件路径规则不同，随便写个相对路径，换台机器就不是那么回事了。

所以后来我给自己定了个规矩：所有 Qt 项目，开工第一件事就是搭一套统一的日志宏。用宏而不是函数，主要是为了自动携带__FILE__、__FUNCTION__、__LINE__这些编译期信息，这样调用方无需手动传参。这套宏本身不复杂，但要把细节抠到位——分级、格式化、文件输出、性能开销、多线程安全——还是有不少讲究的。

下面我把自己的实践方案完整拆开讲，从最朴素的宏定义思路开始，一步步做到能直接进工程用的版本。

2. 日志宏的雏形：从 qDebug 到 LOG_INFO

2.1 先理解 Qt 日志机制的底层

Qt 的日志系统其实是有层级的。最底层是全局函数qInstallMessageHandler，你可以把它理解成一道水闸：qDebug()、qInfo()、qWarning()、qCritical()等所有输出最终都会汇聚到一个地方，由默认的消息处理器统一分发到控制台。

默认的处理器行为是：

• qDebug()/qInfo()：输出到 stdout
• qWarning()/qCritical()：输出到 stderr
• QtFatal()：输出后直接 abort

搞清楚这一点很重要，因为如果你的日志宏最终只是包一层qDebug()，那你根本没法统一拦截、统一格式化、统一写文件。真正务实的做法是保留 Qt 原生日志 API 的调用方式，但安装一个自定义的messageHandler，在处理器里完成时间、级别、线程号、文件行号的拼装，再把成品字符串转发给控制台和文件。

这么设计的好处很明显：你不需要在宏里做字符串格式化这种脏活，宏只负责把编译期信息送进参数列表，剩下的事情全部交给处理器去做。这样一来，宏定义非常轻薄，改动日志格式也只需改一个函数，不用动几十处调用点。

2.2 第一版宏定义

先看一个最基础的版本，目的是让每个日志自动带上文件名、函数名和行号：

#ifndef LOGGER_H #define LOGGER_H #include <QString> #define LOG_INFO(msg) \ qInfo("%s | %s:%d | %s", \ __FUNCTION__, \ __FILE__, \ __LINE__, \ msg) #endif // LOGGER_H

用法很简单：

LOG_INFO("this is a test");

输出效果类似：

main | /home/user/project/main.cpp:12 | this is a test

这里有个小问题：__FILE__打出来是完整路径，又长又丑。通常我们会用__FILE_NAME__来只取文件名，但这是 C++20 的东西，老编译器不一定支持。更通用的做法是在宏里做一次字符串裁剪：

#define LOG_INFO(msg) \ qInfo("%s | %s:%d | %s", \ __FUNCTION__, \ (strrchr(__FILE__, '/') ? strrchr(__FILE__, '/') + 1 : __FILE__), \ __LINE__, \ msg)

Windows 下路径分隔符是反斜杠\，最好再兼容一下。实际工程我会写一个小工具函数来处理路径截取，而不是放在宏里，否则每次展开都会调用strrchr，看着脏。

但说实话，这一版宏还远远不够用。因为msg如果是一个QString或者带参表达式，直接塞给%s会出问题。而且日志分级也没有。下一节我们把它升级成完整可用的版本。

3. 完整版日志宏：分级、格式化与惰性求值

3.1 日志级别的设计

我习惯采用五级分级，跟 Qt 自带的级别对齐，方便和qInstallMessageHandler衔接：

这样设计的分级很自然，因为每个宏内部直接调用对应的 Qt 原生函数，Qt 本身的消息处理机制会自动把低级别日志送到我们的统一处理器里。

3.2 用 variadic macros 处理多参数

日志宏最常见的痛点是不能像qDebug() <<那样拼接任意类型。解决办法是利用 C++11 的变参宏和 Qt 的QDebug，但我们需要的是位置参数可控、又能自动加分隔符。说白了，宏要能这样用：

LOG_INFO("user login", "uid:", userId, "role:", roleName);

而不是手动拼成一个QString。为此我采用一个折中方案：宏参数全部交给一个模板函数，用QDebug逐个写入，最终生成一个QString，再交给 Qt 日志系统。

这里给出一个可编译的完整实现思路，头文件我命名为Logger.h：

#ifndef LOGGER_H #define LOGGER_H #include <QString> #include <QDebug> #include <QtGlobal> // 获取简短文件名 inline const char* logFileName(const char* file) { const char* p = strrchr(file, '/'); if (p) return p + 1; p = strrchr(file, '\\'); if (p) return p + 1; return file; } // 拼接函数：任何类型都能转成字符串 template<typename T> void logFormat(QString& out, const T& val) { QDebug deb(&out); deb << val; } inline void logFormat(QString& out, const QString& val) { out += val; } // 递归终止 inline void logFormatArgs(QString&) {} template<typename T, typename... Args> void logFormatArgs(QString& out, const T& first, const Args&... rest) { logFormat(out, first); logFormatArgs(out, rest...); } // 真正的日志函数 inline void logMessage(int level, const char* file, int line, const char* func, const QString& msg) { // 这里可以调用 qDebug/qInfo/qWarning/qCritical // 但更推荐统一调用一个底层函数 // 我们将在下一节用 qInstallMessageHandler 统一接管 switch (level) { case 0: qDebug().noquote() << msg; break; case 1: qDebug().noquote() << msg; break; case 2: qInfo().noquote() << msg; break; case 3: qWarning().noquote() << msg; break; case 4: qCritical().noquote() << msg; break; case 5: qFatal("%s", msg.toUtf8().constData()); break; default: qDebug().noquote() << msg; break; } } #define LOG_TRACE(...) logMessage(0, logFileName(__FILE__), __LINE__, __FUNCTION__, QString()) #define LOG_DEBUG(...) logMessage(1, logFileName(__FILE__), __LINE__, __FUNCTION__, QString()) #define LOG_INFO(...) logMessage(2, logFileName(__FILE__), __LINE__, __FUNCTION__, QString()) #define LOG_WARN(...) logMessage(3, logFileName(__FILE__), __LINE__, __FUNCTION__, QString()) #define LOG_ERROR(...) logMessage(4, logFileName(__FILE__), __LINE__, __FUNCTION__, QString()) #define LOG_FATAL(...) logMessage(5, logFileName(__FILE__), __LINE__, __FUNCTION__, QString()) #endif // LOGGER_H

上面的代码有缺陷：QString()直接传进去等于把参数丢了。这里我们把参数收集逻辑补上：

#define LOG_INFO(...) \ do { \ QString _msg; \ logFormatArgs(_msg, ##__VA_ARGS__); \ logMessage(2, logFileName(__FILE__), __LINE__, __FUNCTION__, _msg); \ } while(0)

##__VA_ARGS__是 GCC/Clang/MSVC 都支持的可变参数宏扩展，允许空参。这样LOG_INFO("hello")和LOG_INFO("hello", 42)都能编译。

logFormat里用了QDebug(&out)，这是因为QDebug可以构造一个输出到QString的实例，operator<<会往字符串里追加格式化内容。不同版本 Qt 可能有细微差别，比如新版 Qt 6 中QDebug构造方式有调整，但思路一致。实测下来，这个拼接方案比QString("%1 %2").arg(a).arg(b)更通用，因为QDebug能识别更多 Qt 类型，比如QSize、QPointF、枚举值等，写起来也不用操心占位符数量。

3.3 惰性求值和编译期裁剪

很多人写日志宏会忽略一个性能问题：日志参数如果是一个开销很大的表达式，比如serializeObject(obj)，那么不管当前级别是否启用，表达式都会被计算。这在 debug 日志里尤其致命。

解决办法是让宏在编译期判断当前编译级别。我通常会定义：

#ifndef LOG_LEVEL #define LOG_LEVEL 4 // 编译期日志等级，发布版可改为 3 或 2 #endif

然后在宏展开前检查级别：

#define LOG_INFO(...) \ do { \ if constexpr (LOG_LEVEL >= 2) { \ QString _msg; \ logFormatArgs(_msg, ##__VA_ARGS__); \ logMessage(2, logFileName(__FILE__), __LINE__, __FUNCTION__, _msg); \ } \ } while(0)

注意：if constexpr是 C++17 特性，如果你的编译器只支持 C++14，可以退而求其次用普通if，但参数表达式仍会被求值，只是运行时跳过了格式化。如果你在 C++17 环境，if constexpr可以真正做到编译期剪枝，连带有副作用的表达式都不会执行。如果非要兼容老标准，可以把参数包进 lambda 里延迟调用，不过这会牺牲一点可读性，我一般不建议上这种黑魔法。

3.4 自定义 messageHandler：接管所有 Qt 日志

现在宏已经能携带文件行号了，但输出还只是简单地交给qDebug()，格式并不统一。下面安装自定义处理器。先看代码：

#include <QFile> #include <QTextStream> #include <QMutex> #include <QDateTime> #include <QDir> static QFile* g_logFile = nullptr; static QTextStream* g_logStream = nullptr; static QMutex g_logMutex; void logMessageHandler(QtMsgType type, const QMessageLogContext& context, const QString& msg) { QMutexLocker locker(&g_logMutex); const char* levelStr = ""; switch (type) { case QtDebugMsg: levelStr = "DEBUG"; break; case QtInfoMsg: levelStr = "INFO"; break; case QtWarningMsg: levelStr = "WARN"; break; case QtCriticalMsg: levelStr = "ERROR"; break; case QtFatalMsg: levelStr = "FATAL"; break; } QString fileName = context.file ? logFileName(context.file) : QString("unknown"); int line = context.line; QString function = context.function ? context.function : QString("unknown"); QString timestamp = QDateTime::currentDateTime().toString("yyyy-MM-dd hh:mm:ss.zzz"); QString formatted = QString("%1 [%2] %3:%4 | %5 | %6") .arg(timestamp) .arg(levelStr, -5) // 左对齐，占5位 .arg(fileName) .arg(line) .arg(function) .arg(msg); // 输出到控制台 QTextStream cerr(stderr); cerr << formatted << Qt::endl; // 输出到文件 if (g_logStream) { (*g_logStream) << formatted << Qt::endl; g_logStream->flush(); } }

安装方式很简单，在main.cpp里：

#include "Logger.h" int main(int argc, char *argv[]) { QApplication app(argc, argv); initLogger("./logs/app.log"); // ... }

initLogger负责打开文件、安装 handler：

void initLogger(const QString& filePath) { QDir dir(QFileInfo(filePath).absolutePath()); if (!dir.exists()) { dir.mkpath("."); } g_logFile = new QFile(filePath); if (g_logFile->open(QIODevice::WriteOnly | QIODevice::Append)) { g_logStream = new QTextStream(g_logFile); } qInstallMessageHandler(logMessageHandler); }

注意文件打开方式，我建议用Append追加模式，而不是Truncate。因为程序运行中崩溃后，你希望上一次的日志还能保留，方便排查。有些项目喜欢每次启动新建一份带时间戳的文件，这也是好习惯，可以这样：

QString timestamp = QDateTime::currentDateTime().toString("yyyyMMdd_hhmmss"); QString filePath = QString("./logs/app_%1.log").arg(timestamp);

然后initLogger(filePath)，这样日志文件不会无限膨胀，也方便按时间归档。

到此为止，一个基本的宏定义 + 统一格式化 + 输出文件的闭环已经建立了。接下来要处理几个真正考验细节的问题。

4. 输出文件环节的工程化细节

4.1 路径、权限与编码

日志文件路径别写死。我见过太多人写fopen("log.txt")，程序一部署到别的目录就找不到文件，或者没有写权限。更稳妥的做法是把日志文件路径放到一个配置类里，或者至少通过QStandardPaths::writableLocation(QStandardPaths::AppDataLocation)来获取当前用户的写目录。

比如：

QString dir = QStandardPaths::writableLocation(QStandardPaths::AppDataLocation); QDir().mkpath(dir); QString logPath = dir + "/logs/app.log";

这样在 Windows 和 Linux 下都能正确落到用户有权限的地方，不会出现装到 Program Files 后写不了文件的问题。

编码方面，Windows 下控制台输出中文可能乱码。默认QTextStream(stderr)走的是本地编码，如果你在纯 Windows 控制台测试，建议统一用QTextCodec或者干脆让文件输出走 UTF-8。我这里给出的方案是：控制台输出走stderr本身，不做强制转码；文件输出用QTextStream时设置一下编码：

g_logStream->setEncoding(QStringConverter::Utf8); // Qt 6

如果是 Qt 5，可以用g_logStream->setCodec("UTF-8")。这样日志文件用任何现代编辑器打开都是正常中文，不至于出现乱码导致事后分析崩溃。

4.2 轮转与大小限制

当程序长时间运行时，单份日志文件会越来越大，有的能到几个 GB，打开、搜索都成问题。处理方式有两种：

一是按大小轮转，当日志文件超过阈值时，把当前文件改名或删除，重新创建新文件。实现并不复杂，可以在logMessageHandler里，每次写入前检查g_logFile->size()，超过MAX_LOG_SIZE就关闭旧文件，重命名成app.1.log，再新建app.log。

二是按天切分，文件名里带日期，跨天自动切换。这个在写日志时判断当前日期和文件记录日期不一致即可。

我实际项目里更喜欢两者结合：默认 20MB 轮转，最多保留 5 个历史备份。这样一个长期跑的后台服务，日志总量始终可控，排查问题只要找最新的那几份就行。

4.3 多线程安全

Qt 程序多线程很常见。如果两个线程同时调LOG_INFO，QTextStream的并发写会导致文件内容错乱甚至崩溃。g_logMutex就是为了这个准备的。但要注意，QMutexLocker锁住的时间要尽量短。我在处理器里先格式化完整字符串，再一次性写入，就是为了lock期间只做 append 操作，不穿插其他耗时操作。如果线程数量特别多，还可以用QRecursiveMutex防止某个线程内部递归打日志导致死锁（比如日志模块内部出错时又触发了日志调用）。这个坑比较隐蔽，我踩过一次，所以重点提示。

4.4 控制台输出与文件输出之间的缓冲

默认情况下，stderr是不带缓冲的，所以控制台输出基本即时可见。文件流我每次写完都flush，虽然牺牲了一点点性能，但能保证程序崩溃时日志不丢失。如果你对性能要求较高，可以改成定时 flush，比如每秒一次，但那样崩溃时最后一两秒的日志可能丢，自己权衡。

5. 宏的使用姿势与避坑经验

5.1 参数类型要注意的坑

QDebug虽然能处理很多类型，但指针和char*之间有歧义。比如：

const char* name = "Tom"; LOG_INFO("name:", name);

这里logFormat模板会匹配到const char*，输出的是字符串内容，没问题。但如果你传的是void*指针，比如LOG_INFO("object:", (void*)obj)，它会输出地址，这符合预期。麻烦的是char*指向的是缓冲区，但你想输出地址而不是内容，那就需要强转。这种歧义在团队协同时尤其容易出问题，我的建议是：日志参数尽量用QString和基础数值类型，别传裸指针。

5.2 不要在高频循环里打日志

即使宏再轻，文件 I/O 和锁开销也经不起千万次调用。一个典型反面教材：

for (int i = 0; i < 1000000; i++) { LOG_DEBUG("i =", i); }

这会让程序慢好几个数量级，而且日志文件瞬间爆炸。正确做法是在循环外打摘要，或者加上频控：每 1000 次迭代打一条。我自己还会在发布版本把LOG_LEVEL设置到 2 或 3，直接屏蔽掉 DEBUG 和 TRACE，从编译期消除这部分开销。

5.3 日志内容别过度拼接

有些同事喜欢一行日志里塞一堆信息，看起来高大上，其实排错时很难定位。日志讲究的是"一眼能看懂"。我习惯的格式是：

2025-02-11 15:22:33.123 [INFO] network.cpp:42 | NetworkManager::onConnected | connection established, server=192.168.1.10

功能、模块、关键变量、结果，一目了然。如果你塞了嵌套结构体序列化结果，几百个字符一长串，反而难以快速扫描。

5.4 发布版该不该关日志

我的建议是：不要全关，但严格控制级别。发布版保留 WARN 和 ERROR 级别的日志，并输出到文件，这对现场问题的回溯非常有帮助。把LOG_LEVEL设为 3 即可。当然客户环境可能很敏感，日志中不能出现密码、密钥、完整身份证号之类的敏感数据，这是基本红线，宏本身帮不了你这个，只能靠团队自查和代码评审来保证。

6. 从日志到辅助调试：文件输出之外还能怎么玩

既然我们已经接管了全局消息处理器，那就不止能写文件了。稍微扩展一下，可以做出几件顺手又省力的事。

第一，重定向 Qt 自身的警告。很多第三方模块内部会用qWarning()输出来警告，比如数据库驱动、网络模块。默认它们会混到你代码里一起刷屏，但这样其实不错——因为你能统一捕获它们，并记录到文件里。尤其是开发阶段，这些警告往往是问题的先兆。

第二，crash 时自动存档。在logMessageHandler里捕获到QtFatalMsg时，除了输出日志，还可以主动把当前日志文件复制一份为crash_yyyyMMdd_hhmmss.log，方便崩溃后单独分析。不少项目还会趁机把系统信息（操作系统版本、Qt 版本、内存占用）一并追加进去，这些信息对远程排障非常有价值。

第三，日志过滤系统。在宏里加一个模块名参数，比如LOG_INFO_MODULE("Network", "connect ok")，然后在 handler 里可以根据模块名动态开关某类日志。这个对于线上问题定位特别管用，比如只打开网络模块的日志，其他一律静默。

第四，异步写日志。如果程序对实时性要求极高，可以在 handler 里只往一个队列里塞字符串，由另一个线程统一写文件，避免日志 I/O 拖慢业务线程。实现也不复杂，用QQueue加QWaitCondition即可。但要注意，程序崩溃时队列里的日志可能来不及落盘，所以崩溃处理要单独加钩子。

7. 一套被验证过的完整模板

说了这么多，直接给一份我目前在用的精简版完整模板，你复制到工程里改改就能用。

Logger.h：

#ifndef LOGGER_H #define LOGGER_H #include <QString> #include <QtGlobal> #include <QDebug> #include <cstring> #ifndef LOG_LEVEL #define LOG_LEVEL 4 #endif inline const char* logFileName(const char* file) { const char* p = strrchr(file, '/'); if (p) return p + 1; p = strrchr(file, '\\'); return p ? p + 1 : file; } template<typename T> void logFormat(QString& out, const T& val) { QDebug deb(&out); deb.noquote() << val; } inline void logFormat(QString& out, const QString& val) { out += val; } inline void logFormatArgs(QString&) {} template<typename T, typename... Args> void logFormatArgs(QString& out, const T& first, const Args&... rest) { logFormat(out, first); logFormatArgs(out, rest...); } void logMessage(int level, const char* file, int line, const char* func, const QString& msg); #ifdef LOG_LEVEL #if LOG_LEVEL >= 0 #define LOG_TRACE(...) \ do { \ QString _msg; \ logFormatArgs(_msg, ##__VA_ARGS__); \ logMessage(0, logFileName(__FILE__), __LINE__, __FUNCTION__, _msg); \ } while (0) #endif #if LOG_LEVEL >= 1 #define LOG_DEBUG(...) \ do { \ QString _msg; \ logFormatArgs(_msg, ##__VA_ARGS__); \ logMessage(1, logFileName(__FILE__), __LINE__, __FUNCTION__, _msg); \ } while (0) #endif #if LOG_LEVEL >= 2 #define LOG_INFO(...) \ do { \ QString _msg; \ logFormatArgs(_msg, ##__VA_ARGS__); \ logMessage(2, logFileName(__FILE__), __LINE__, __FUNCTION__, _msg); \ } while (0) #endif #if LOG_LEVEL >= 3 #define LOG_WARN(...) \ do { \ QString _msg; \ logFormatArgs(_msg, ##__VA_ARGS__); \ logMessage(3, logFileName(__FILE__), __LINE__, __FUNCTION__, _msg); \ } while (0) #endif #if LOG_LEVEL >= 4 #define LOG_ERROR(...) \ do { \ QString _msg; \ logFormatArgs(_msg, ##__VA_ARGS__); \ logMessage(4, logFileName(__FILE__), __LINE__, __FUNCTION__, _msg); \ } while (0) #endif #else // 如果 LOG_LEVEL 未定义，则全部可用 #define LOG_TRACE(...) logMessage(0, logFileName(__FILE__), __LINE__, __FUNCTION__, QString()) #define LOG_DEBUG(...) logMessage(1, logFileName(__FILE__), __LINE__, __FUNCTION__, QString()) #define LOG_INFO(...) logMessage(2, logFileName(__FILE__), __LINE__, __FUNCTION__, QString()) #define LOG_WARN(...) logMessage(3, logFileName(__FILE__), __LINE__, __FUNCTION__, QString()) #define LOG_ERROR(...) logMessage(4, logFileName(__FILE__), __LINE__, __FUNCTION__, QString()) #endif #endif // LOGGER_H

注意：为了减少篇幅，上面的宏里省略了参数拼接。实际使用时你应该像前面那样在宏内部先构造_msg再传给logMessage，而不是直接传QString()。建议你把完整拼接版本照前文组合起来。

Logger.cpp：

#include "Logger.h" #include <QFile> #include <QTextStream> #include <QMutex> #include <QMutexLocker> #include <QDateTime> #include <QDir> #include <QFileInfo> #include <QStandardPaths> #include <cstdio> static QFile* g_logFile = nullptr; static QTextStream* g_logStream = nullptr; static QMutex g_logMutex; void logMessage(int level, const char* file, int line, const char* func, const QString& msg) { // 分级符号映射到 QtMsgType，供统一 handler 使用 // 但这里我们直接调用 qDebug/qInfo 等，让默认 handler 去处理也可以 // 为了格式统一，我们更推荐直接写一套私有输出逻辑 QMutexLocker locker(&g_logMutex); QString levelStr; switch (level) { case 0: levelStr = "TRACE"; break; case 1: levelStr = "DEBUG"; break; case 2: levelStr = "INFO"; break; case 3: levelStr = "WARN"; break; case 4: levelStr = "ERROR"; break; case 5: levelStr = "FATAL"; break; default: levelStr = "LOG"; break; } QString formatted = QString("%1 [%2] %3:%4 | %5 | %6") .arg(QDateTime::currentDateTime().toString("yyyy-MM-dd hh:mm:ss.zzz")) .arg(levelStr, -5) .arg(file) .arg(line) .arg(func) .arg(msg); QTextStream cerr(stderr); cerr << formatted << Qt::endl; if (g_logStream) { (*g_logStream) << formatted << Qt::endl; g_logStream->flush(); } } void initLogger(const QString& logDir, const QString& prefix) { QString dirPath = logDir.isEmpty() ? QStandardPaths::writableLocation(QStandardPaths::AppDataLocation) + "/logs" : logDir; QDir dir(dirPath); if (!dir.exists()) { dir.mkpath("."); } QString fileName = QString("%1/%2_%3.log") .arg(dirPath) .arg(prefix.isEmpty() ? "app" : prefix) .arg(QDateTime::currentDateTime().toString("yyyyMMdd_hhmmss")); g_logFile = new QFile(fileName); if (g_logFile->open(QIODevice::WriteOnly | QIODevice::Append)) { g_logStream = new QTextStream(g_logFile); #if QT_VERSION >= QT_VERSION_CHECK(6,0,0) g_logStream->setEncoding(QStringConverter::Utf8); #else g_logStream->setCodec("UTF-8"); #endif } } void shutdownLogger() { qInstallMessageHandler(nullptr); if (g_logStream) { g_logStream->flush(); delete g_logStream; g_logStream = nullptr; } if (g_logFile) { g_logFile->close(); delete g_logFile; g_logFile = nullptr; } }

上面这套是我在几个实际项目中滚动迭代过的版本。消息处理器那节我故意没在里面调用qInstallMessageHandler，是为了让你先看清楚结构化输出的基本逻辑。如果你想完全统一接管 Qt 原生日志，把logMessage里的输出代码抽到logMessageHandler里，然后在initLogger中qInstallMessageHandler(logMessageHandler)即可。

8. 关于这套方案的性能与取舍，再聊两句

有人可能会觉得，每次写日志都用QMutex加锁，会不会成为性能瓶颈？说实话，如果你的程序每秒打日志不超过几千条，这点锁开销完全可以忽略。真正影响性能的是写文件操作本身，尤其在高频次场景下。所以思路应该是：降低日志频率，而不是优化单次写入的速度。5.2 节里那个高频循环的例子，再快的锁都救不了。

还有一点，QDebug deb(&out)在 Qt 6 里的构造方式我写了QDebug(&out)，但在某些 Qt 版本里QDebug不允许在栈上这样构造，会变成QDebug(QtMsgType)这种形式。如果你遇到编译不过，请查阅你手头 Qt 版本的QDebug构造函数。另外一个更跨版本的写法是：

QString out; QTextStream ts(&out); ts << val;

这样通用性更强，代价是对 Qt 的流运算符支持不如QDebug丰富，但应付常规类型和自定类型已经够用。为了避免踩版本差异的坑，我这边的工程基本都是按我手头主用的 Qt 版本来写，但如果你的项目需要跨 Qt5/Qt6 编译，建议把logFormat统一改成QTextStream方案。

日志宏这件事，说白了就是"早做早省心"。一旦你习惯了带行号、带函数名、带级别、带文件的日志，再回头去用裸qDebug()，会觉得像是在裸奔。特别是当你接手一个半年没动的老项目，打开日志文件看到清晰的上下文，那种感觉，比写多少注释都管用。