简介：CuteLogger 是一套面向 Qt 开发者的轻量级日志库，适合需要在桌面端或 Android 平台实现日志记录、分类过滤与性能测时的中高级 Qt 程序员。该库几乎能记录文件名、源代码行号与函数签名，支持文件、控制台、Android logcat 等多种附加程序，也可自定义输出格式；同时兼容 Qt 内置类型，可直接替代 qDebug 使用，并具备线程安全、日志类别、耗时统计等实用特性。压缩包共20个文件，其中10个头文件定义接口、9个cpp文件提供各附加程序与日志管理器的具体实现，另有1个pri文件便于工程引入，整体仅29KB，代码量少且结构清晰，按接口、实现分区，易于定位和裁剪。当前已有925人学习该资源，下载后即可得到完整源码，对了解 Qt 日志机制、二次开发或快速集成日志方案都很有参考价值，尤其适合在项目里快速搭建自己的日志模块。
1. CuteLogger 到底解决什么问题：别再只盯着 qDebug 了
排查 Qt 程序问题的时候，你有没有遇到过这种场景：现场设备跑了一个月，某个操作偶发崩溃，用户描述不清操作步骤，你在办公室复现不出来。这时候最想要的就是一份能记录崩溃前完整操作轨迹的日志文件。单纯靠 qDebug 往控制台打，程序一关输出就没了，跨平台到 Windows 服务、嵌入式 Linux 设备上，控制台根本不存在。CuteLogger 就是一个专门解决这个问题的 Qt 日志库，体积小、不依赖额外第三方库，几个文件就能集成进现有工程。它能把 qDebug、qWarning、qCritical 的全部输出改写到文件、控制台、系统调试口，还自带日志滚动和格式控制。适合从桌面工具、工业上位机到嵌入式 Linux 设备的任何 Qt 项目，尤其是没有现成日志体系、又迫切需要一个跨平台落盘方案的团队。
2. 先看清它的家底：两个核心类与一个完整日志框架
2.1 核心类划分：Logger 与 Appender
CuteLogger 的架构极简，整个库由两个核心类撑起来：一个是 Logger，负责全局日志配置和消息路由；另一个是 AbstractAppender 体系，负责具体的日志输出目标。Logger 在内部持有全部已注册的 Appender，每产生一条日志消息，就按照配置好的格式把消息广播给所有 Appender。这个设计跟 Qt 自身的消息处理机制结合得非常好，因为 Logger 内部通过 qInstallMessageHandler 拦截了 Qt 全局的消息输出，所以程序里原本的 qDebug、qWarning、qCritical 不需要改一行代码，输出就会被自动接管。
Appender 这边，库内置了几种常见实现：ConsoleAppender 输出到标准输出，FileAppender 输出到普通文件，RollingFileAppender 支持按文件大小滚动输出，DebugOutputAppender 输出到 Windows 调试器。RollingFileAppender 是日常用的最多的一个，因为它解决了单个日志文件无限膨胀的问题——几十 MB 的 Qt 程序跑上一天，日志文件轻松上 GB，没有滚动机制根本没法维护。
以我最常用的部署方式为例，我一般会在应用启动早期创建 Logger 单例，然后挂上一个 RollingFileAppender 指向当前的日志目录：
Logger* logger = Logger::instance(); RollingFileAppender* fileAppender = new RollingFileAppender(); fileAppender->setFormat("%{time} [%{type}] %{message}"); fileAppender->setLogFilePath("/var/log/myapp/log.txt"); fileAppender->setMaxFileSize(10 * 1024 * 1024); fileAppender->setMaxBackupIndex(5); logger->registerAppender(fileAppender);这里有几个关键参数需要解释。setMaxFileSize 设置的是单个日志文件达到多少字节后触发滚动，单位是字节，这里写了 10MB；setMaxBackupIndex 决定保留几个历史文件，超出后最早的备份会被删除。消息格式里 %{time} 输出时间戳，%{type} 输出日志级别，%{message} 输出正文内容。顺序可以随意调整，但建议把时间放最前面，方便定位问题时间线。
2.2 日志级别与线程安全：嵌入式设备上最容易忽略的细节
CuteLogger 在实现上把日志级别和线程安全放在了一个很重要的位置。Qt 自身的消息类型有 QtDebugMsg、QtWarningMsg、QtCriticalMsg、QtFatalMsg 四类，CuteLogger 在拦截之后会转换成对应的内部日志级别，同时额外区分了 Info、Trace、Error 等更细粒度级别。它的逻辑是：qInfo 输出到 Info，qDebug 输出到 Debug，qWarning 输出到 Warning，qCritical 输出到 Error，qFatal 对应 Fatal。你可以在运行时通过 Logger 的 setLogLevel 设置最低输出级别，低于这个级别的消息会被全部丢弃，这个特性在排查性能问题时很有用——不用改代码注释，直接调运行参数就能控制日志量。
线程安全方面，CuteLogger 的每个 Appender 内部都维护了自己的互斥锁，写入文件时锁定以保证并发安全。这意味着你在任意线程调用 qDebug，输出都不会交错或写入半个消息。在实际项目中，我会把 Logger 初始化和 Appender 注册放在 main 函数里最早执行的位置，早于任何工作线程创建。
int main(int argc, char *argv[]) { QApplication app(argc, argv); Logger::instance(); configureLogging(); // 后续启动工作线程 return app.exec(); }这样做的理由是：如果工作线程先开始产生日志，再注册 Logger，那之前的日志就丢掉了。另外这个库还支持 QLoggingCategory 的接入，qCDebug(category, ...) 系列宏的输出也能被它捕获。但这里有个细节要留意：必须在 CuteLogger 注册了消息拦截器之后，Qt 的 category 输出才会走 CuteLogger 的管道。如果顺序反了，消息还是会落到默认的 stderr 上。
2.3 从零搭建的选型思路
我在第一次接触这个库时也犹豫过要不要直接用 Qt 自带的 qtlogging 配置。Qt 其实允许通过 qtlogging.ini 或环境变量控制日志规则，比如 QT_LOGGING_RULES 可以按 category 开关日志。但它的落盘方案太原始，只有一个消息模式做格式控制，既不支持文件滚动，也不支持按大小分文件，更不支持多个 Appender 同时输出到不同目标。而 CuteLogger 提供的是一个完整框架：拦截全局消息后，每条日志会依次经过过滤、格式化、分发三个环节。过滤决定要不要记录，格式化决定记录的文本长什么样，分发决定记录到哪些目标。你甚至可以把同一套日志同时写到文件和网络，只需要注册多个 Appender 即可。
编译参数上还有一个容易踩的细节：CuteLogger 源码里有多个版本分支，老版本用 C++11 特性，新版本用了 C++14 甚至 C++17 的语法。集成前先确认你的 Qt 版本和编译器标准。用 Qt 5.9 配老编译器时，尽量选早期 tag；Qt 6 项目直接拿新版本源码用就行。
3. 落地集成：从源码包到跑起来的三条路
3.1 直接加入源码参与构建：最稳妥的方式
拿到 CuteLogger.rar 解压之后，里面是完整的源码目录，没有经过编译的预编译库文件。最直接的方式就是把源码直接放进你的 Qt 工程里一起编译。这种方式没有库路径的烦恼，调试的时候还可以直接跟进源码里看消息处理逻辑。操作上就是把 CuteLogger 的 src 目录加入工程：
QT += core TEMPLATE = app CONFIG += c++14 SOURCES += main.cpp \ ../3rdparty/CuteLogger/src/Logger.cpp \ ../3rdparty/CuteLogger/src/AbstractAppender.cpp \ ../3rdparty/CuteLogger/src/ConsoleAppender.cpp \ ../3rdparty/CuteLogger/src/FileAppender.cpp \ ../3rdparty/CuteLogger/src/RollingFileAppender.cpp \ ../3rdparty/CuteLogger/src/DebugOutputAppender.cpp HEADERS += \ ../3rdparty/CuteLogger/src/CuteLogger.h \ ../3rdparty/CuteLogger/src/Logger.h \ ../3rdparty/CuteLogger/src/AbstractAppender.h \ ../3rdparty/CuteLogger/src/ConsoleAppender.h \ ../3rdparty/CuteLogger/src/FileAppender.h \ ../3rdparty/CuteLogger/src/RollingFileAppender.h \ ../3rdparty/CuteLogger/src/DebugOutputAppender.h这段 pro 文件里用相对路径把第三方源码拉进工程。我觉得直接编译源码最大的好处是调试方便——你设个断点在 Logger 中，可以亲眼看到 qDebug 是如何被拦截、格式化、写入文件的。整个流程不再是黑匣子。不过 SOURCES 里不要偷懒用通配符，显式列出可以让工程文件在任何平台上行为一致。
3.2 通过 pri 文件集成：不同的构建系统有不同的姿势
源码包内一般还带了一个 CuteLogger.pri 文件，如果拿到的话，集成会更简单。pri 文件本质上是 qmake 的片段，可以在你的工程里用一行 include 引入：
include(../3rdparty/CuteLogger/CuteLogger.pri)include 之后，CuteLogger 的全部源文件、头文件路径、编译宏就自动被加到当前工程里了。注意 include 这一行的位置要写在存在的变量赋值之后，比如你先定义了 QT += core，后面再去 include，避免 pri 内部依赖的变量还没有定义好。另外，有的版本里 pri 会引用相对路径，如果你的工程和源码包不在同一个父目录下，需要按实际情况调整路径层次。
3.3 CMake 方式集成：适合新工程和跨平台团队
如果你的工程已经走在 CMake 构建的路线上，那源码包同样可以用 target_sources 逐个加入编译单元。CMake 下要额外关注 AUTOMOC 和 AUTOUIC 的处理：头文件里有 Q_OBJECT 类需要被 moc 处理，这要求在 CMakeLists 中设置 CMAKE_AUTOMOC ON。以下是我常用的配置：
cmake_minimum_required(VERSION 3.16) project(MyApp LANGUAGES CXX) set(CMAKE_CXX_STANDARD 14) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_AUTOMOC ON) add_executable(MyApp main.cpp ../3rdparty/CuteLogger/src/Logger.cpp ../3rdparty/CuteLogger/src/AbstractAppender.cpp ../3rdparty/CuteLogger/src/ConsoleAppender.cpp ../3rdparty/CuteLogger/src/FileAppender.cpp ../3rdparty/CuteLogger/src/RollingFileAppender.cpp ../3rdparty/CuteLogger/src/DebugOutputAppender.cpp ) target_include_directories(MyApp PRIVATE ../3rdparty/CuteLogger/src )CMake 方式里最容易翻车的一点：忘记把 CuteLogger 的 src 目录加进 include 路径，导致 CuteLogger.h 头文件找不到。还有一个隐蔽的坑是，如果同一份日志源码同时被多个 target 引用，CMake 可能会把这些目标里相同符号的重复定义拌在一起。建议一个进程只允许一个 target 链接这套日志源码。
3.4 动态库方式的取舍
源码包理论上也可以自己编译成一个动态库再让主程序链接，毕竟有些团队习惯把所有公共组件编译成 so/dll。我实际试过一次，后来放弃了动态库方案。原因有两个：一是 CuteLogger 的日志输出依赖于注册的 message handler，而 handler 的状态是进程级的，如果库被多个模块加载，谁先初始化谁就决定了全局消息走向，容易打架；二是动态库的调试体验比源码差不少，出了问题还得把断点放进库里，反而多一道环节。
我真正推荐的动态库使用场景是：多个 Qt 程序要共享同一套日志目录和格式约定，单独抽一个动态库做统一 log 接口。但那样的话，你把 CuteLogger 封装一层更好的接口再导出也不迟，而不应该裸导库源码。
4. 配置日志策略：格式化、滚动与过滤
4.1 格式化：%{} 占位符是控制信息的唯一入口
CuteLogger 的日志格式是配置主导的，不写代码到处拼接字符串。核心的格式字符串主要在 AbstractAppender 的 setFormat 方法上设置。支持的占位符包括 %{time}、%{type}、%{level}、%{category}、%{thread}、%{function}、%{message}，以及进程相关的 %{pid} 等。所有这些占位符，Appender 在每次写日志时会替换成实际内容。一个标准的推荐格式是：
fileAppender->setFormat("%{time=y-MM-ddTHH:mm:ss.zzz} [%{type}] (%{thread}) %{message}");这里 setFormat 的参数里，time 后面指定了 y-MM-ddTHH:mm:ss.zzz 的时间精度格式，T 只是字面分隔符。thread 显示的是线程 ID，排查并发相关问题特别有用。%{type} 会比 %{level} 更接近 Qt 原生的语义，如果你习惯看 qDebug/qWarning 这组字眼，就用 %{type}；如果你更想把级别抽象成 Info/Debug/Error，就用 %{level}。注意设置格式后应立即验证一次输出，因为不同版本对占位符的支持程度不完全一致，老版本可能不支持 %{function} 等新增项。
格式上的另一个细节是空格对齐。比如你希望 ERROR 级别一眼就能看到，可以把格式改为%{type=9}，后面跟的 9 表示最小对齐宽度，类型文本不足 9 个字符时补空格。上线前把这些小细节调好，运维时去看日志会舒服很多。
4.2 滚动策略：大小滚动是最稳的选型
RollingFileAppender 支持两种滚动模式：按文件大小滚动和按时间周期滚动。按大小滚动用 setMaxFileSize 设置上限，按时间滚动用 setDatePattern 设置周期模式。我的习惯是优先采用按大小滚动，原因在真实项目里碰过跟头：按日期滚动虽然文件个数好预期，但单文件可能会被一条超长错误堆栈瞬间撑爆，导致整个文件进程卡死。大小滚动天然限制了最坏情况的单文件体积，对稳定性更友好。
滚动命名方式默认是 log.txt、log.txt.1、log.txt.2 这样的命名序列。调参提示：如果你希望备份文件带时间戳，源码里 RollingFileAppender 还有一些扩展接口，后面进阶章节我再展开。文件备份的索引规则也值得留意：索引越小代表越新。比如 log.txt.1 是最近的备份，log.txt.2 是上一次滚动留下的。排错的时候先看 log.txt 覆盖的是最新的滚动段，再回退到 log.txt.1。
4.3 过滤：控制日志的仓库开关
日志量大了之后，过滤器的作用不亚于格式化。CuteLogger 的 AbstractAppender 提供了一个便捷的过滤接口，每个 Appender 可以设置一个最小日志级别。这意味着你可以把 errorAppender 设置为只记录 Error 级别的消息，把 debugAppender 设置为跟踪 Debug 级别。典型的配置方式如下：
ConsoleAppender* console = new ConsoleAppender(); console->setFormat("%{message}"); console->setThreshold(Logger::WarningLevel); Logger::instance()->registerAppender(console);上面这段代码里我建了一个 ConsoleAppender，并且通过 setThreshold 设置为 WarningLevel。效果是：Debug 和 Info 级别的日志完全不在控制台显示，而 Warning 及以上的消息照常输出。很多人在调试阶段把所有级别全部打开，上线前不降级，结果日志文件快速增长，真正出问题时重要的信息被淹没在无关 log 里。这也是一个常见的误用场景。
另外，CuteLogger 支持运行时对 Logger 本身设置全局日志级别。比如程序运行时没接收任何参数的默认级别是 DebugLevel，如果你传入--quiet，就执行 logger->setLogLevel(Logger::WarningLevel)，这样全局只输出警告以上级别的日志。运行时调整的好处是，业务代码里原有的一堆 qDebug 不用删，只在启动时动态决定哪些级别需要保留。
5. 常见问题与避坑：集成 CuteLogger 会踩到的五个坑
5.1 日志文件不生成，程序静默失败
现象是：程序正常运行，控制台没有输出，文件目录里也找不到日志文件。原因通常有两个：一是设置的目标日志文件路径不存在，而 CuteLogger 不会主动创建多级目录。比如你在 setLogFilePath 里写了 /var/log/myapp/log.txt，但 /var/log/myapp 目录不存在，文件自然写不进去。第二个常见原因是权限，/var/log 目录通常只有 root 可写，你的 Qt 程序跑在普通用户下，写入被拒绝。解决方式是：程序启动时先 QDir().mkpath() 创建目录，再注册 FileAppender，同时检查 openForWrite 的返回值，打一条 qDebug 确认日志系统已经启动。
QDir dir("/var/log/myapp"); if (!dir.exists()) { dir.mkpath("."); } fileAppender->setLogFilePath("/var/log/myapp/log.txt");这段代码里 mkpath 创建的是多级目录，exists 判断目录是否已存在。建议把 mkpath 的结果打印出来，如果返回 false 就要立刻检查权限。还有一点，如果你把日志路径设为相对路径，要注意当前工作目录和可执行文件目录不一定相同，这在部署到 systemd 服务或者 Windows 服务时尤其明显。
5.2 qSetMessagePattern 与 CuteLogger 相互覆盖
现象：你原本在 main 函数开头用 qSetMessagePattern 设置了带颜色和时间戳的 qDebug 格式，集成 CuteLogger 之后却发现控制台输出格式乱了，要么是你设的格式完全失效，要么是颜色代码不断出现。原因是 CuteLogger 调用 qInstallMessageHandler 接管了 Qt 的全局消息输出，而 qSetMessagePattern 设置的模式只对 Qt 默认 handler 生效。一旦你的自定义 handler 接了手，qSetMessagePattern 也就没了作用。解决方式是：所有格式化需求全部收敛到 CuteLogger 的 setFormat 里去做，不要混着用。如果你一定保留 qSetMessagePattern，那就要在 Logger 注册的消息处理器里手动调用 qFormatLogMessage 来尊重已有的 pattern。
5.3 中文日志乱码，尤其是在 Windows 上
现象：中文字符在控制台和日志文件里变成乱码。原因可能是字符编码不匹配。Linux 下通常 UTF-8 是默认编码，问题不大；Windows 下 CuteLogger 写入文件时，不同版本默认用的编码不一致，有些版本用本地编码，有些用 UTF-8。解决方式是在 RollingFileAppender 上显式设置编码：fileAppender->setEncoding("UTF-8")。如果日志要打开到 Windows 自带的记事本查看，可以参考源码确认这套编码设置是否真的写入了 UTF-8 BOM。没有 BOM 的 UTF-8 文件在老式记事本下仍可能被识别成 ANSI 而显示乱码。理想的工程做法是统一用 UTF-8 存日志，读取时用现代文本编辑器。
5.4 滚动文件大小测试不生效
现象：你按文档设置了 setMaxFileSize(1024) 期望 1KB 就滚动一次，结果写了几十 KB 都没动静。原因是 RollingFileAppender 的内部实现里，检查滚动条件的时机是在日志消息被写入后触发的，它并不是实时按字节数卡脖子，而是按写入的累计字节与 maxFileSize 做一次比较。如果你单条日志本身很长，一条日志就能超过 maxFileSize，那它会在写完后立刻滚动一次，属于正常情况。但如果你一条日志只有几十字节，期望每次写满 1KB 就滚动，它是绝对无法精确控制到字节级边界的。直观理解就是：滚动是一个检查点机制，不是水龙头开满就关的那种精准阀。
如果确实需要非常小体积的测试验证滚动功能，把 maxFileSize 设成很小的值，比如 256 字节，然后写几条日志观察文件名序列的变化。
5.5 多个 Appender 输出同一份日志的重复与顺序问题
现象：你注册了 ConsoleAppender 和 RollingFileAppender 同时输出，发现某些消息只在控制台出现，或者顺序时序不对。原因：不同 Appender 内部各自有互斥锁，虽然每条消息的总体顺序是按产生顺序派发的，但多个 Appender 的写操作是独立完成的，快速并发下你在文件里看到的顺序和产生顺序可能略有偏差。最直观的影响是：一条 qCritical 可能在文件里排在稍早的 qDebug 前面一点点。解决方式是：不要试图用多 Appender 去拼接完整时间线，文件用文件，控制台用控制台。如果必须以文件为准，就只写注册文件的 appender，控制台排查问题用调试器输出。这套方案是够用的，毕竟你真实排错时更愿意看文件时间线和分类过滤过的控制台输出。
6. 进阶技巧：给滚动日志文件加上时间戳与启动标记
到这一步，基础集成已经跑通，你也有了稳定的日志文件。不过线上环境还可以再进一步：日志文件名带上时间戳，启动时写入一条系统信息标记。这个技巧在无人值守设备上特别实用——系统重启过多少次、每次启动对应的日志在哪一个文件，一眼就能看到。
我给 CuteLogger 做的一个常用扩展，是把 RollingFileAppender 的固定文件名改成一个带当前日期时间的路径，然后在程序启动时写入一行包含版本、PID 和启动时间的标记。做法不复杂，不需要改库源码，只要在初始化时动态构造文件名：
QDateTime now = QDateTime::currentDateTime(); QString logFileName = QString("app_%1.log") .arg(now.toString("yyyyMMdd_HHmmss")); fileAppender->setLogFilePath(QDir::currentPath() + "/logs/" + logFileName); Logger::instance()->registerAppender(fileAppender); qInfo("===== app started, pid=%d, version=%s =====", QCoreApplication::applicationPid(), APP_VERSION);代码里的关键点是：QDateTime::currentDateTime() 在程序启动时取一次当前时间，用它拼进日志文件名。好处是保证一个进程一条日志文件，不会因为多次启动覆盖同名文件。如果一天内多次重启，文件名能精确到秒，同样不冲突。qInfo 这一行会走 CuteLogger 的管道，正常落盘到刚创建的文件里。
如果你的程序还涉及日志文件按天归档的需求，可以在启动标记之后，单独启动一个 QTimer 定时检查日期是否变化，变化了就动态切换 Appender 的日志文件。核心逻辑是移除旧 appender、更新路径、重新注册：
if (dayChanged) { Logger::instance()->unregisterAppender(fileAppender); QString newName = QString("app_%1.log").arg(QDate::currentDate().toString("yyyyMMdd")); fileAppender->setLogFilePath(baseDir + "/" + newName); Logger::instance()->registerAppender(fileAppender); }在切换过程中，旧日志文件会自然关闭，新日志从新文件名开始写入。注意 unregisterAppender 之后要把指针保存好，等新路径设置完再重新注册。这套扩展我没有写死到 CuteLogger 源码里，而是单独封装在自己的日志控制类中，因为这样保持了对上游源码的可更新性。
从那以后，我每次搭建 Qt 软件的信息化日志体系，都会强制把 CuteLogger 的初始化单独放在一个日志控制类中，并且始终坚持三条习惯：目录不存在就不启动、格式统一用时间戳开头、滚动策略留给运维同学配置。这套基于 CuteLogger 的思路支撑了不少现场问题的快速定位，希望帮到你。
本文还有配套的精品资源，点击获取
