简介面向QT框架下C开发者的日志保存功能实例核心目标是让日志文件达到预设大小或满足特定条件时自动切换并新建文件适合在桌面应用、工具软件或跨平台项目中补充轻量级日志能力。压缩包共六个文件包含两个C源文件、一个头文件、一个工程文件、一份使用说明和一个用户配置文件整体仅6KB代码量小便于快速学习。工程以SaveLogPro项目为样例覆盖日志路径设置、日志消息写入、写入前文件大小检查、达到限制后自动创建新文件等关键环节并演示文件读写与文件信息获取相关工具类的典型用法。已有2378人学习下载。阅读源码即可掌握自定义日志记录的基本框架并可继续扩展日志等级、时间戳、线程标识等元数据让软件更易维护、问题更易排查适合希望从零实现日志滚动策略的中高级开发者。 凌晨三点被现场电话叫醒。远程桌面连过去程序界面倒是活着业务线程却卡死了。我习惯性地先翻日志结果只有控制台窗口里残留的几百行 qDebug 输出——程序半夜重启过一次之前的输出全没了。那个晚上之后我把“日志必须落盘、必须按条件自动分文件”写进了自己所有 Qt 项目的默认配置。今天聊的这套方案就是我在几个 Qt 桌面项目里反复打磨过的日志模块保存日志数据根据条件自动创建日志文件。这里的“条件”不是花活而是实打实的运维需求——日期变了要开新文件、文件太大要轮转、错误级别要有单独的归置。实现难度本身不高但拆解需求、处理边界、绕开坑的细节才是这篇文章真正值钱的部分。不管你是正准备给 Qt 项目补日志系统还是被现场问题逼着重构日志模块这套代码和思路都可以直接照抄。1. 先想清楚日志系统到底要解决哪三个问题我见过不少人写日志模块上来就new一个 QFile 往里面塞字符串塞了两天发现文件好几个 GB又急着加轮转。其实动手之前把问题拆开代码结构会完全不一样。第一个问题信息留得住。qDebug 默认打到控制台程序一崩滚动缓冲区里的内容就没了。Windows 下更惨控制台缓冲区默认只有几千行程序跑一晚上你只能看到最近几分钟的输出。所以日志的第一需求是落盘而且要尽量保证进程崩溃前最新的内容已经写到了磁盘上。第二个问题文件管得住。如果所有日志永远写进同一个文件个把月下来就是几个 GB。打开慢、查找慢、备份慢最后只能手动删。所以文件必须能按条件自动切分——这就是“根据条件自动创建日志文件”这句话的出处。条件设计得好等于给日志文件上了按需归档的机制日常维护成本和排查成本都会低很多。第三个问题问题找得到。日志是给人看的。现场反馈“11 点 35 分界面卡了一下”你能不能在一分钟内定位到 11:35 前后发生了什么这取决于文件命名是否带日期、每行内容是否带精确到毫秒的时间戳、错误日志有没有快速入口。这三个问题想明白之后代码怎么写都是顺理成章的。2. 文件怎么切日期、级别、大小、模块四种条件怎么选“根据条件自动创建日志文件”这句话里条件才是灵魂。把需求拆开来看常见条件有四种各有各的适用场景。条件文件命名示例解决什么问题触发时机日期app_20250114.log按天归档方便按日期查跨天后的第一次写入日志级别app_20250114_error.log错误快速入口收到 Error 级消息文件大小app_20250114_001.log防止单文件无限膨胀超过设定阈值模块/类别app_network_20250114.log按业务模块隔离消息 category 匹配日期条件应该是默认动作。绝大多数项目都要按天分文件。原因是排查问题最常见的问题就是“今天和昨天哪儿不一样”按天归档文件数量和单个文件大小都可控。跨天自动开新文件这个逻辑实现起来很简单但收益立竿见影。级别条件适合单独立个入口。现场运维人员通常不是 C 工程师让他从几万条 Debug 级别日志里翻 Error还不如直接打开一个 error.log。这也是我在实现里让 Error 级别额外写一份文件的直接原因。运维只要会用记事本打开 error.log就能在第一时间把错误内容反馈回来。大小条件本质上是一个保护机制。一般和日期条件叠加使用。单个文件超过阈值就轮转旧文件改名保留新文件继续写。这样就算程序半年不重启日志文件也不会变成一个 10GB 的怪物。写轮转逻辑时要注意轮转是基于“当前文件大小”判断的所以每次写入前检查一次m_file.size()就够了不需要额外维护计数器。模块条件要克制。知道qInstallMessageHandler的消息上下文里带 category 字段之后很多人会忍不住给每个模块开一个文件。我的建议是初期不要超过三个模块文件文件越多出问题时翻找的路径就越多。只有“网络日志单独留存”这种硬需求出现了再加也不迟。拿磁盘空间算一笔账假设一条日志平均 120 字节10MB 的文件大概能存 8.7 万条桌面程序正常运行一天写三五万条已经算多的了所以 10MB/天的阈值在多数场景下都够用。把阈值除以平均条数你就能估算出文件要几天轮转一次按这个来调大小比拍脑袋靠谱。3. 核心实现Logger 类从声明到落盘的完整代码这一节直接给可抄的代码。类的设计原则很简单单例、线程安全、条件切换文件。3.1 文件命名规则不打开就知道内容普通日志app_yyyyMMdd.log例如app_20250114.log跨天自动换新文件。轮转文件app_yyyyMMdd_1.log、app_yyyyMMdd_2.log序号递增避免覆盖。错误日志app_yyyyMMdd_error.log独立入口方便现场快速定位。命名规则定好之后代码里所有逻辑都围绕这三个规则展开不需要挂任何数据库或者索引文件名本身就是元数据。3.2 头文件与初始化// logger.h #pragma once #include QFile #include QTextStream #include QMutex #include QDate class Logger { public: enum Level { Debug 0, Info, Warn, Error }; static Logger instance(); void init(const QString dirPath, int maxSizeKB 10240); void write(Level level, const QString tag, const QString msg); private: Logger() default; ~Logger(); bool openLogFile(const QDate date); void rotateLogFile(); QString m_dirPath; QFile m_file; QTextStream m_stream; QMutex m_mutex; QDate m_currentDate; qint64 m_maxSize 10 * 1024 * 1024; };这里有两个设计点需要解释。第一instance()返回单例但内部用new而不是栈对象Logger Logger::instance() { static Logger *logger new Logger(); return *logger; }这是为了避免静态对象析构顺序问题。程序退出时如果某个全局对象在 Logger 析构之后还调用了 qDebug栈上的单例已经没了就会出现未定义行为。故意让这个对象在进程退出时泄漏反而安全。代价是析构函数不会执行但因为我们每条日志都 flush所以不需要担心缓冲数据丢失。第二QFile和QTextStream要在实例内部长期持有不要在每次写日志时重新打开文件。文件描述符反复开关性能和稳定性都会变差而且容易留下“上一秒文件还在写、下一秒就被别的模块删了”这种诡异问题。3.3 条件触发逻辑跨天、轮转、错误单独落盘#include logger.h #include QDir #include QDateTime #include QMutexLocker void Logger::init(const QString dirPath, int maxSizeKB) { QMutexLocker locker(m_mutex); m_dirPath dirPath; m_maxSize qint64(maxSizeKB) * 1024; QDir dir; if (!dir.exists(m_dirPath)) dir.mkpath(m_dirPath); openLogFile(QDate::currentDate()); } bool Logger::openLogFile(const QDate date) { if (m_file.isOpen()) { m_stream.flush(); m_file.close(); } const QString fileName QString(%1/app_%2.log) .arg(m_dirPath) .arg(date.toString(yyyyMMdd)); m_file.setFileName(fileName); if (!m_file.open(QIODevice::WriteOnly | QIODevice::Append | QIODevice::Text)) return false; m_stream.setDevice(m_file); m_stream.setCodec(UTF-8); // Qt6 推荐 m_stream.setEncoding(QStringConverter::Utf8) m_currentDate date; return true; }上面有一个非常容易漏的细节打开文件时必须同时加Append。很多同学只写WriteOnly结果程序第二次启动时把上一次的日志全部覆盖了排查问题排了个寂寞。Text模式则保证\n会被转换成平台对应的换行符跨平台行为更一致。接下来是核心的 write 方法三个条件都集中在这里触发void Logger::write(Level level, const QString tag, const QString msg) { QMutexLocker locker(m_mutex); // 条件一日期变化自动创建新的当天文件 QDate today QDate::currentDate(); if (!m_file.isOpen() || m_currentDate ! today) openLogFile(today); // 条件二文件超过阈值轮转 if (m_maxSize 0 m_file.size() m_maxSize) rotateLogFile(); // 条件三错误级别单独落一份 error 文件 if (level Error) { QFile errFile(QString(%1/app_%2_error.log) .arg(m_dirPath) .arg(today.toString(yyyyMMdd))); if (errFile.open(QIODevice::WriteOnly | QIODevice::Append | QIODevice::Text)) { QTextStream errStream(errFile); errStream.setCodec(UTF-8); errStream QDateTime::currentDateTime().toString(yyyy-MM-dd hh:mm:ss.zzz) [Error] msg \n; errStream.flush(); } } static const char *levelNames[] { Debug, Info, Warn, Error }; m_stream QDateTime::currentDateTime().toString(yyyy-MM-dd hh:mm:ss.zzz) [ levelNames[level] ] [ tag ] msg \n; m_stream.flush(); }3.4 轮转逻辑先改名再开新文件void Logger::rotateLogFile() { if (!m_file.isOpen()) return; m_stream.flush(); m_file.close(); const QString base QString(%1/app_%2) .arg(m_dirPath) .arg(m_currentDate.toString(yyyyMMdd)); const QString oldPath base .log; int index 1; QString newPath; do { newPath QString(%1_%2.log).arg(base).arg(index); } while (QFile::exists(newPath)); // 如果 rename 失败文件被占用等放弃本次轮转下次写入再试 if (QFile::rename(oldPath, newPath)) openLogFile(m_currentDate); }轮转采用“旧文件改名、新文件重建”的策略被轮转的历史文件会保留下来方便调阅旧日志新文件继续使用标准命名程序其他逻辑不需要感知轮转序号。关于每条日志都flush()我在这套方案里是刻意保留的。QTextStream 默认有缓冲如果进程被强杀或崩溃缓冲区里没写出去的内容就丢了。逐条 flush 能保证崩溃前最后一条日志大概率已经落盘。这确实是拿磁盘 IO 次数换安全性但对桌面程序一天几万条的日志量来说代价完全可接受。4. 让 qDebug 自动进文件接入 qInstallMessageHandlerLogger 写好了但如果业务代码还在用 qDebug()日志还是不会进文件。Qt 的消息机制是qDebug、qWarning、qCritical、qInfo 最终都会调用“消息处理器”。默认处理器把内容打到 stderr我们把它替换成自己的函数所有调试输出就会统一走进 Logger。void appMessageHandler(QtMsgType type, const QMessageLogContext ctx, const QString msg) { Logger::Level level Logger::Info; switch (type) { case QtDebugMsg: level Logger::Debug; break; case QtInfoMsg: level Logger::Info; break; case QtWarningMsg: level Logger::Warn; break; case QtCriticalMsg: case QtFatalMsg: level Logger::Error; break; } QString tag ctx.category ? QString::fromUtf8(ctx.category) : QStringLiteral(app); // 重要这里绝不能再调用 qDebug / qWarning否则会递归调用自己 Logger::instance().write(level, tag, msg); // 安装自定义 handler 后默认控制台输出会消失手动保留一份方便调试 if (level Logger::Warn) fprintf(stderr, %s\n, qPrintable(msg)); }在 main() 里的接入顺序是关键int main(int argc, char *argv[]) { QApplication app(argc, argv); Logger::instance().init(logs); // 先初始化日志目录 qInstallMessageHandler(appMessageHandler); // 再安装消息处理器 qDebug() application started; // ... }为什么先 init 再 install因为 init 之后的第一条 qDebug 就会触发 handler 写入文件此时目录已经建好、文件已经打开。反过来如果 init 之前就调用了 qDebugwrite 会尝试初始化打开文件此时目录路径还是空的日志就会丢。所以 main 里的顺序别颠倒。还有两个细节值得注意。一个是qInstallMessageHandler的返回值它返回之前安装的 handler。如果你在集成第三方库时也装了 handler可以先保存旧的在自己的 handler 里做链式转发避免把别人的输出弄丢。另一个是QtFatalMsgqFatal 的 handler 执行完之后程序默认仍会 abort所以 fatal 级别的日志必须保证在 handler 内部写完并 flush。不要把 fatal 消息塞进队列等后台线程慢慢写程序可能没机会写了。5. 多线程写入一把锁够不够性能实话说Qt 的 qDebug 可以在任意线程调用消息 handler 会在调用者线程里同步执行。也就是说如果四个工作线程同时在打日志你的 write() 会被四个线程并发进入。QFile 和 QTextStream 都不是线程安全的所以我在 write() 里用 QMutexLocker 包了整个写入过程。这样所有线程的日志写入被串行化同一时间只有一条日志在写文件不会出现内容交叉缠绕、文件名错乱这类问题。代价是写日志变成临界区理论上某个线程写大文件时其他线程会卡在锁上。实际测下来这套“逐行 flush 加锁”的方案在我办公用的 i5 机器、普通 SSD 上能稳定跑大概三万到五万条/秒。桌面程序正常业务每秒能打几十条日志就算密集了这个吞吐量富余得很。但有两类程序不能用这个方案。第一类是高频率采集程序比如每秒上千条波形数据、串口报文、网络包。逐行 flush 的磁盘 IO 很快会把采集线程拖慢。这类程序应该把日志写入放到独立线程里业务线程只负责把格式化好的日志文本塞进线程安全队列后台日志线程取队列写文件。队列要有上限满的时候优先丢日志而不是阻塞采集线程——高频场景丢几十条日志可接受把采集延迟拉大不可接受。第二类是日志量极大的后台服务数据量级到了每秒几万条锁本身就是瓶颈需要无锁环形缓冲加批量落盘这种更重的设计。不过这对 Qt 桌面项目来说基本遇不到没必要提前上。我自己的经验是先跑通带锁的简单方案然后加一个开关在程序启动参数里允许切换“同步写”和“异步队列写”。实际部署下来绝大多数项目停在同步写就够了异步方案只在一个音频采集项目里真正开过。6. 上线前必须处理的六个细节日志模块能跑只是第一步下面这些细节全是我在真实项目里踩过的没处理之前不要上生产。6.1 编码Windows 下的中文乱码QTextStream 的默认编码在 Windows 上是本地代码页GBK 系列。如果代码里保持默认生成的日志文件用 UTF-8 编辑器打开就会乱码。所以openLogFile里我固定m_stream.setCodec(UTF-8)Qt6 里用m_stream.setEncoding(QStringConverter::Utf8)。查看日志的工具也统一按 UTF-8 打开。6.2 目录没权限日志“消失”的最大嫌疑如果程序安装在C:\Program Files下默认没有写权限。init 里的 mkpath 会失败openLogFile 也会失败。很多朋友遇到“日志没生成”第一反应是怀疑代码其实先看一眼安装目录的权限。桌面程序建议把日志目录放到用户数据目录也就是QStandardPaths::writableLocation(QStandardPaths::AppDataLocation)或者程序目录下建 logs 子目录并保证安装时给了写权限。我习惯用前者一劳永逸。6.3 文件被占用日志系统不能拖垮业务Notepad、Excel、日志上传工具打开着日志文件时程序里 QFile::open 会失败。如果这是写日志的必经路径业务线程可能因为等待文件锁而卡顿。我的降级策略是open 失败时把这条日志直接fprintf(stderr, ...)日志系统本身坏了但绝不能把业务带崩。记住这个原则日志系统永远是辅助不是主角。6.4 老日志自动清理按日期分文件之后日志文件数量会持续增长。我通常保留 30 天启动时扫一遍目录void cleanOldLogs(const QString dirPath, int keepDays) { QDir dir(dirPath); const QStringList files dir.entryList(QStringList() *.log, QDir::Files); const QDateTime deadline QDateTime::currentDateTime().addDays(-keepDays); for (const QString name : files) { QFileInfo info(dir.filePath(name)); if (info.lastModified() deadline) QFile::remove(info.filePath()); } }保留天数按磁盘空间和业务要求调。30 天、10MB/天就是 300MB 左右一般项目都能接受。6.5 时区跨时区部署时别用裸本地时间单机桌面程序用本地时间没有问题。但如果日志要汇总到服务器或者设备部署在不同时区文件名字面上的“日期”就会对不上。这种场景建议文件名和内容统一用 UTC并在内容里带上时区偏移或者同时保留本地时间和 UTC分析时按需取用。6.6 时间戳格式毫秒是定位问题的底牌日志内容里我固定用yyyy-MM-dd hh:mm:ss.zzz。毫秒看起来不起眼但一旦涉及线程竞争、网络超时这类需要判断先后顺序的问题没有毫秒你根本没法定罪。这一条我从一开始就写死从未后悔过。这套 Logger 我前后用了好几年代码从一个类膨胀到带异步队列、带网络上报的完整模块然后又删回一个类。如果现在让我从头选我还是建议先用最简单的那版——一个文件、一把锁、按条件切文件跑出第一版数据再决定要不要加花活。日志系统最怕的不是功能少而是功能多到没人愿意维护。最后一个小技巧把 Logger 的初始化做进一个全局的“启动配置”函数和配置文件读取、数据库连接放在一起保证从业务第一条日志起就有地方去。这个习惯能让你少熬很多个凌晨三点的夜。本文还有配套的精品资源点击获取