简介面向C开发者的QT日志模块示例源码聚焦“按条件自动创建日志文件”这一常见需求适合需要为桌面应用补充日志系统的初中级QT程序员。方案给出从日志路径设定、文件滚动策略到按大小自动切分文件的完整实现思路并涉及QDir、QFile、QFileInfo、QTextStream等核心类的配合用法。压缩包共6个文件以cpp实现、h头文件、pro工程配置为主附带说明文档整体仅6KB结构精简便于快速阅读与移植。已有2383人学习下载。通过分析其中的SaveLogPro小工程可直观掌握自定义日志类的初始化、写入接口、文件大小检查与错误处理等关键环节还能进一步扩展日志级别、时间戳等元数据用于提升软件可维护性与问题排查效率。1. 深夜排查线上崩溃我栽在了一个几十MB的日志文件上做上位机开发的大概率经历过这种电话凌晨两点现场说程序崩了远程上去一看日志文件攒了几十MB全是循环打印的调试信息真正有价值的崩溃上下文早被冲没了。想按天查某段运行状态日志却混在一个文件里只能开着编辑器满文件翻。“QT 保存日志数据根据条件自动创建日志文件”这个需求就是从这种场景里长出来的。这套 QT/C 日志模块能在程序运行期间按日期、按日志级别、按文件大小三个维度自动切分文件让日志目录保持规律运维拿到文件名就知道该看哪一份。它适合长时间运行的上位机、采集设备、视觉检测和边缘计算类程序也适合任何受够了“单文件日志越来越大”的C工程师。2. 项目定位与技术选型为什么选 QFile 加轻量规则而不是开源日志库2.1 它解决的问题和适用场景日志模块的痛点往往不是“能不能写”而是“写完之后能不能用”。一套程序在设备上连续跑三个月如果只有一个 app.log故障排查时要么用 grep 从头翻要么把几十MB的文件整个拉回来慢慢看。常见的解决思路是在落盘前定义规则——这些规则恰好对应日志文件自动创建的触发条件日期切换跨天时自动生成按日期命名的独立文件实现按天归档级别切换ERROR、WARN 单独落到独立文件故障时只看关键日志大小切换单个文件超过容量上限后自动编号分割避免单文件无限膨胀适用场景非常具体工控上位机需要无人值守运行几个月视觉检测程序跑在车间需要把每帧处理结果留出运行轨迹采集网关每隔几秒从串口或网络拿数还要按天归档给后端分析。这些场景有两个共同点现场没有专职运维定期清理日志故障发生时辅助手段很有限日志文件本身的规律性往往是第一道防线。2.2 为什么不用现成的第三方库有人会问QT 里写日志直接上 spdlog 或 log4qt 不香吗答案是分情况。第三方库成熟、功能多但在这个场景下反而需要做减法。它们有自己的一套格式体系、滚动策略和初始化流程却不知道也不关心上位机界面上的时钟格式更不能天然理解“错误日志单独放一个文件”这种业务语义。真要接进来还得套一层适配层把条件拆分规则翻译给库去执行这层翻译的成本和自研相比并不划算。另一个现实因素是部署环境。客户现场往往禁止引入额外动态库依赖能用一个自包含的源码级模块解决问题就不多带一个 so 或 dll。在这类上位机项目里源码直接编进主程序整个目录拷到设备上就能跑这本身就是验收条件。用 Qt 自带的 QFile、QDir、QDateTime、QMutex 组合起来逻辑完全受自己控制条件判断和文件切换的时机都能按需求微调。后续加字段、加策略也都是在自己的代码上改不用去读第三方库的滚动器源码。2.3 类的划分三个协作者各管一段整体代码不复杂但刻意做了三层拆分避免业务代码和文件细节混成一锅粥。管理类 LoggerManager 是唯一入口承担线程同步和条件调度LoggerFile 负责具体文件的创建、写入、关闭和滚动LoggerConfig 负责从配置文件读取参数并提供默认值。业务层永远只和 LoggerManager 打交道目录路径、文件名规则、滚动条件都封装在内部业务代码里看不到任何与文件相关的细节。调用关系大致是业务线程调用 LoggerManager 的 write 方法 → 加锁 → 判断是否需要滚动 → 如果需要让 LoggerFile 关闭当前文件并打开新文件 → 写入消息 → 按配置决定是否立即 flush。这条链路里最关键的一点是滚动判断发生在写入之前新消息永远进新文件不会出现“本应落在新文件里却写进了旧文件”的错位。对外接口非常简洁核心就是几个宏。下面这段来自 logger_global.h#define LOG_DEBUG LoggerManager::instance().debug #define LOG_INFO LoggerManager::instance().info #define LOG_WARN LoggerManager::instance().warn #define LOG_ERROR LoggerManager::instance().error业务代码只需要包含 logger_global.h然后像用 qDebug 一样调用宏即可内部会转发到管理类的同名方法统一拼装时间戳和级别。宏的好处是调用点短不会在业务方法里引出几行长代码坏处是日志开关完全交给了运行时配置如果哪天想用编译期裁剪还需要再包一层条件宏这个留给二次开发处理。管理类选择单例不是图省事而是这个模块天然需要全局唯一的文件句柄和锁对象。程序里任何一处写日志都必须走同一个实例否则两个实例各持一把锁、各开一个文件进程里日志就直接分家了。C11 之后静态局部变量的初始化是线程安全的instance() 本身没有竞争问题锁只需要保护下面的写路径。职责对照表可以看得更清楚类名对外职责内部核心成员LoggerManager单例入口、线程同步、滚动调度m_mutex、m_file、m_configLoggerFile文件句柄、滚动、写入QFile、QTextStream、m_creationDateLoggerConfig参数装载与默认值QSettings、maxFileSizeBytes、splitByDate3. 核心模块拆解从程序启动到日志自动落盘的完整链路这一章直接踩着代码讲把初始化、滚动判断、写入闭环和三处边界处理都说透。理解了这条链路后面改配置、加策略都会顺手很多。3.1 单例初始化与配置装载业务代码启动时一般在 main() 里做一次初始化int main(int argc, char *argv[]) { QApplication app(argc, argv); LoggerManager::instance().init(config/logger.ini); // ... 业务逻辑 }LoggerManager 的 init 实现大致是这样的void LoggerManager::init(const QString configPath) { QMutexLocker locker(m_mutex); if (m_initialized) { qWarning() logger had been initialized, ignored.; return; } m_configPath configPath.isEmpty() ? defaultConfigPath() : configPath; m_config.load(m_configPath); QDir dir(m_config.logDir); if (!dir.exists()) { dir.mkpath(.); } m_file.reset(new LoggerFile(m_config)); m_file-openCurrentFile(QDateTime::currentDateTime()); m_initialized true; }逻辑说明这里加锁保护初始化过程防止两个线程同时调用 init 导致文件句柄二次打开。m_config.load内部会先写入默认值再尝试从 ini 读取覆盖所以配置文件缺失时不会直接翻车而是按内置参数继续运行。openCurrentFile把打开结果记录在内部成员里后续写入前可以快速检查句柄有效性。参数方面configPath支持相对路径和绝对路径。相对路径以进程工作目录为基准正式发布时建议在 init 里转成绝对路径这样无论从快捷方式还是命令行启动日志落点都是确定的。3.2 条件判断三个维度决定何时切文件滚动判断是整个模块里最核心的逻辑传入即将写入的日志级别返回 true 就表示需要切新文件bool LoggerManager::needsRolling(Level incomingLevel) { if (m_file-size() m_config.maxFileSizeBytes) { return true; } if (m_config.splitByDate m_file-creationDate() ! QDate::currentDate()) { return true; } if (m_config.splitByLevel incomingLevel ! m_file-level()) { return true; } return false; }参数说明incomingLevel是当前这条日志的级别creationDate是文件创建时记录下来的日期一旦跨天必然不等于当天level是当前文件绑定的日志级别在按级别拆分时同一文件只接收同一级别的日志。三个条件之间是“或”关系任何一个成立都会触发滚动。滚动动作封装在rollIfNeeded里void LoggerManager::rollIfNeeded(Level incomingLevel) { if (!m_file-isOpen()) { m_file-openNewFile(QDateTime::currentDateTime()); } else if (needsRolling(incomingLevel)) { m_file-closeAndArchive(); m_file-openNewFile(QDateTime::currentDateTime()); } }这里closeAndArchive并不是单纯 close还会按配置决定是否把旧文件挪到 archive 子目录。对于只按大小分割的场景close 之后再 openNewFile 会自动带上序号避免同名文件互相覆盖。不同配置组合下文件名的形态差别很大日期加级别20240415_error.log、20240415_debug.log日期加大小20240415_001.log、20240415_002.log纯级别error.log、info.log文件名规则建议在项目一开始就定死后续所有归档、清理、跨天判断都围绕这套命名来展开改动命名规则会牵动几乎所有周边逻辑。3.3 写入路径与线程安全写日志的主路径保持简单void LoggerManager::write(Level lv, const QString msg) { QMutexLocker locker(m_mutex); if (!m_initialized) return; rollIfNeeded(lv); QString line formatLine(lv, msg); m_file-writeLine(line); }formatLine 负责把时间戳、级别、线程 ID、消息拼成一行QString LoggerManager::formatLine(Level lv, const QString msg) { return QString([%1][%2][tid:%3] %4) .arg(QDateTime::currentDateTime().toString(yyyy-MM-dd hh:mm:ss.zzz)) .arg(levelName(lv)) .arg(QString::number((quint64)QThread::currentThreadId())) .arg(msg); }逻辑说明整段 write 全程持锁包括滚动判断和文件写入都锁在同一个临界区里。选择大粒度锁是因为滚动和写入是强相关操作如果在滚动判断后放锁另一个线程可能趁虚而入写进旧文件。业务日志写入频率通常不高大粒度锁的竞争可以忽略换来的是绝对安全。这个取舍对日志模块来说是值得的。这里不建议用 QReadWriteLock 做优化因为写操作占绝大多数每次写入都要修改文件偏移量本质还是互斥写读写锁不会带来收益。文件层写入用 QTextStream 包 QFile并在每行后做 flushvoid LoggerFile::writeLine(const QString line) { if (!m_stream.isNull()) { m_stream line \n; m_stream.flush(); } }每次 flush 确实有性能开销但在日志场景里提供两个实际价值一是程序被强杀时最多只丢正在写的那一行而不是缓冲里积压的一批二是日志可以被 tail -f 实时查看现场调试时不用反复重启程序才能看到新输出。等业务写入量真的达到每秒几百条时再改成定时 flush 也不迟。3.4 边界情况时间回拨、写入失败、编码偏差日志系统还会遇到一些平时不起眼、真遇上就懵的情况。时间回拨是其中一个比较隐蔽的问题设备跨时区或者手动校时QDateTime 往回跳如果按日期判断就可能导致文件来回切换产生一堆空文件。一个常见做法是加入幂等判断只有在文件创建日期和新日期确实不同并且当前时间比文件最后写入时间更晚时才触发切换。这样校时造成的抖动不会产生垃圾文件。写入失败要处理的是磁盘满或者权限问题。openNewFile 失败时Manager 不应该反复尝试而是把错误写到 qWarning并把本次写入丢弃掉避免在故障现场再引入新的异常。这里的关键是 openNewFile 返回 false 时write 路径要能安全跳过bool LoggerFile::openNewFile(const QDateTime now) { QString path buildFileName(now); if (m_file.isOpen()) m_file.close(); m_file.setFileName(path); if (!m_file.open(QIODevice::Append | QIODevice::Text)) { qWarning() log file open failed: path m_file.errorString(); return false; } m_stream.setDevice(m_file); return true; }参数说明now是触发打开文件的时间点用于拼进文件名返回 bool 让调用方能判断是否继续写入。如果这里用了 Truncate 模式每次启动都会清空历史日志一定要确认没有误用。编码方面QTextStream 默认按本地编码处理在 Windows 中文环境下写出来的日志可能是 GBK拉到 Linux 上看就乱码。更稳妥的做法是在 LoggerFile 构造函数里显式指定 UTF-8m_stream.setCodec(UTF-8);这样日志文件在任意平台打开都不会出现中文乱码后续做日志上传、入库解析也少一层转换工作。4. 配置驱动改日志分割条件不动一行业务代码4.1 ini 配置项与默认值模块的运行时行为基本都由配置文件驱动这样现场调条件时不需要重新编译。默认配置文件长这样[common] logDir./logs splitByDatetrue splitByLeveltrue maxFileSizeKB5120 flushIntervalMs100 [format] withThreadIdtrue withTimestamptrue timestampFormatyyyy-MM-dd hh:mm:ss.zzz对应 LoggerConfig 里的成员load 时用 QSettings 读取读不到就取默认值。各字段含义如下logDir 是日志根目录splitByDate 开启后文件名带日期splitByLevel 开启后文件名带级别maxFileSizeKB 控制单个文件上限超了就滚动flushIntervalMs 控制定时 flush 的间隔值为 0 表示每次写入立即 flushformat 段控制时间戳和线程号要不要写进日志行。用 QSettings 读 ini 时记得指定 INI 格式否则它会按系统默认格式处理void LoggerConfig::load(const QString path) { QSettings settings(path, QSettings::IniFormat); logDir settings.value(common/logDir, ./logs).toString(); splitByDate settings.value(common/splitByDate, true).toBool(); splitByLevel settings.value(common/splitByLevel, true).toBool(); maxFileSizeBytes settings.value(common/maxFileSizeKB, 5120).toInt() * 1024; flushIntervalMs settings.value(common/flushIntervalMs, 100).toInt(); timestampFormat settings.value(format/timestampFormat, yyyy-MM-dd hh:mm:ss.zzz).toString(); }这里要注意QSettings 对 ini 的小节和键默认用“/”作分隔符所以common/logDir对应 ini 里[common]小节下的 logDir 键。字段名写错不会报错只是会静默读成默认值排查配置问题时要把这点考虑进去。4.2 对外接口业务代码怎么调业务侧看到的接口只有通过宏访问的那几个入口。典型使用方式如下LOG_INFO(device %1 online, ip%2, deviceId, ip); LOG_WARN(temp exceeds threshold: %1, temp); LOG_ERROR(image pipeline failed at frame %1, err%2, frameNo, err);这些宏展开后调用的是模板方法把可变参数拼成一个 QString。模板转发的好处是类型安全传 int、double 时不需要手动转成字符串。对应实现放在头文件里templatetypename... Args void info(const QString fmt, Args... args) { write(Level::Info, formatMessage(fmt, std::forwardArgs(args)...)); }formatMessage 逐次调 QString::arg 完成占位符替换。这里有一个容易被忽略的坑arg 替换是按序执行的如果业务字符串里本身带了“%1”这类字符又刚好和真实参数撞车就会出现替换错位。常见做法是业务侧统一约定文案里不手写数字占位符全部交给接口处理。4.3 集成进 QT 工程的两种方式把 LoggerModule 文件夹放进项目后接入方式有两种。第一种最省事直接在 .pro 里 includeQT core CONFIG console c17 include(LoggerModule/logger.pri)logger.pri 内部把源文件、头文件、包含路径都定义好业务代码只需要 include “logger_global.h”。第二种方式是把日志模块编译成静态库适合在多个业务工程之间复用。需要注意链接的是 Qt5Core 还是 Qt6Core在 .pri 里写清楚否则换个 Qt 版本头文件路径和符号引用都会直接报错。如果项目已经有 QApplication还可以在 init 之后提供一个全局便捷函数 resetConfig()让现场改完配置后不用重启程序。实现思路是按照配置文件重新装载参数并且重建 LoggerFile 对象再重新 open 一次。直接修改 m_config 里某些字段很可能对旧文件失效重建对象是最稳的路径。minLevel 这类过滤需求虽然没有内置到默认配置里但扩展成本很低。在 [common] 段加一个 minLevel2 的字段write 进入主路径前先判断级别是否满足阈值不满足就直接返回能省掉大量无意义的格式化开销。这也是日志模块最常见的一个扩展点。5. 踩坑记录日志模块稳定运行的五个关键细节日志模块的稳定不靠一两行代码靠的是对文件生命周期、线程时序和配置路径的全面控制。下面五个问题我都在真实设备上见过翻车版本有些甚至上线两三个月后才暴露出来。每一条都值得在写完模块后专门写测试用例覆盖。5.1 现象程序被杀后最后几十条日志凭空消失日志文件看起来一切正常但每次用任务管理器强杀进程最后几十条记录就是找不到。问题根源在 QTextStream 的内部缓冲写入文本先落入流缓冲并不会立刻交给操作系统落盘进程被强杀时缓冲内容直接丢弃。解决方法是让 LoggerFile 提供 flush() 并在程序退出路径上调用同时把 flush 间隔变成配置项。我通常会设置默认 100ms 的定时 flushERROR 级别走同步 flush这样既不拖累常规写入也能保证关键信息即时落盘。5.2 现象多线程同时写日志内容串行却又断行两个线程并发写日志时单条日志偶尔被拆成两半中间插入了另一个线程的半行内容日志看起来像被拼错的文本。原因是拼行和写入没有作为一个原子操作业务线程各自调用了 QTextStream而文件偏移量的修改并不是原子操作。解决方法是让所有写入统一经过 LoggerManager 的同一个带锁方法由 QMutexLocker 把整段 write 包括拼行、滚动判断和落盘都保护起来。同样的问题也存在于直接用 fprintf 的场景即使单次 fprintf 在多数平台看起来原子QTextStream 的组合调用也绝不能假设原子。5.3 现象按大小分割后新文件覆盖了旧文件某天单个日志超过 5MB 后继续写后一条日志竟然把前面的内容覆盖掉了一部分。原因通常出在文件名规则上只用了日期加“_new”后缀同一天每次滚动都生成同一个文件名后打开的 Append 模式直接把新内容接在后面业务看起来就像覆盖。解决方法是文件名带滚动序号。每次 openNewFile 前扫描目录里同日期前缀的最大序号序号加一后再创建文件比如生成 20240415_003.log。这里要提醒一点序号判断必须放在 Manager 的锁内否则两个线程同时滚动会生成同一个序号又互相覆盖。5.4 现象跨天时日志时间归属错乱今天的日志进了昨天的文件设备跑过凌晨零点日志的日期明明是今天文件却还是昨天的。常见原因有两个一是只初始化一次m_file 里记录的日期是启动那天的日期跨天判断没有实时刷新二是滚动判断的时机不对比如把日期变化检查放在写入队列之后而不是写入之前。解决方法是每次写入前用 QDateTime::currentDateTime().date() 与当前文件的创建日期做实时比较而不是依赖缓存值。同时坚持滚动动作在写入前执行确保新日志一定进入新文件。5.5 现象日志路径不对翻遍整个目录都找不到日志程序运行正常日志也有内容但运维就是找不到文件。最常见的原因是 logDir 用了相对路径进程工作目录不一致结果就不一样从 IDE 启动时日志在 build 目录从安装目录启动时又落在别处在没有界面的服务程序里尤其难排查。解决方法是 init 时把相对路径标准化成绝对路径并用 qInfo 打印一次实际落盘路径。更进一步的方案是在程序设置界面里展示这样现场点一下就能直达目录。这个细节看上去小实际是现场反馈里出现频率最高的“日志玄学”之一。6. 二次开发给日志模块加上归档清理和异步队列默认实现里日志写入是同步阻塞的每条日志都要进锁并操作文件日志量上来之后会挤占业务线程。改造的第一步通常是加一个异步队列业务线程把格式化好的日志行推入 QQueue另一个工作线程统一消费批量落盘。队列长度要做上限保护消息积压过多时优先丢弃 DEBUG保证 ERROR 一定进队列。这里要特别注意跨天判断和滚动必须在消费线程里做否则队列里的日志归属会乱掉先来后到关系会对不上。第二件值得做的事是归档与定期清理。默认实现目前会无限保留文件对长期运行的设备不健康。可以增加 keepDays 配置项日志滚动或每次启动时扫描日志目录把超过保留期的 .log 文件移动或删除。归档子目录按月份组织运维只需要关注最近几天时直接看根目录即可。第三件建议增加的是进程启动标记每次启动在日志里打一条包含程序版本、启动时间、配置文件路径的记录。设备如果重启过很多次排查问题的第一个人手动作会轻松很多。改造完的验证步骤也不复杂先用脚本或手工改系统时间模拟跨天再用多线程压测循环连续写几千条日志最后检查文件数量、每条日志完整性和跨天归属。我自己动手时习惯把文件命名规则当作接口约束先定死后面所有功能都围绕这套命名展开避免各模块各写一套。这次拆解日志模块我也保持了同样的习惯条件清单先列出来再动代码。从那以后我每次接 QT 日志需求都强制先过一遍日期、级别、大小这些边界条件再用这份代码结构搭建日志路径目录清爽现场排查也少了很多来回。希望帮到你。本文还有配套的精品资源点击获取
简介面向C开发者的QT日志模块示例源码聚焦“按条件自动创建日志文件”这一常见需求适合需要为桌面应用补充日志系统的初中级QT程序员。方案给出从日志路径设定、文件滚动策略到按大小自动切分文件的完整实现思路并涉及QDir、QFile、QFileInfo、QTextStream等核心类的配合用法。压缩包共6个文件以cpp实现、h头文件、pro工程配置为主附带说明文档整体仅6KB结构精简便于快速阅读与移植。已有2383人学习下载。通过分析其中的SaveLogPro小工程可直观掌握自定义日志类的初始化、写入接口、文件大小检查与错误处理等关键环节还能进一步扩展日志级别、时间戳等元数据用于提升软件可维护性与问题排查效率。1. 深夜排查线上崩溃我栽在了一个几十MB的日志文件上做上位机开发的大概率经历过这种电话凌晨两点现场说程序崩了远程上去一看日志文件攒了几十MB全是循环打印的调试信息真正有价值的崩溃上下文早被冲没了。想按天查某段运行状态日志却混在一个文件里只能开着编辑器满文件翻。“QT 保存日志数据根据条件自动创建日志文件”这个需求就是从这种场景里长出来的。这套 QT/C 日志模块能在程序运行期间按日期、按日志级别、按文件大小三个维度自动切分文件让日志目录保持规律运维拿到文件名就知道该看哪一份。它适合长时间运行的上位机、采集设备、视觉检测和边缘计算类程序也适合任何受够了“单文件日志越来越大”的C工程师。2. 项目定位与技术选型为什么选 QFile 加轻量规则而不是开源日志库2.1 它解决的问题和适用场景日志模块的痛点往往不是“能不能写”而是“写完之后能不能用”。一套程序在设备上连续跑三个月如果只有一个 app.log故障排查时要么用 grep 从头翻要么把几十MB的文件整个拉回来慢慢看。常见的解决思路是在落盘前定义规则——这些规则恰好对应日志文件自动创建的触发条件日期切换跨天时自动生成按日期命名的独立文件实现按天归档级别切换ERROR、WARN 单独落到独立文件故障时只看关键日志大小切换单个文件超过容量上限后自动编号分割避免单文件无限膨胀适用场景非常具体工控上位机需要无人值守运行几个月视觉检测程序跑在车间需要把每帧处理结果留出运行轨迹采集网关每隔几秒从串口或网络拿数还要按天归档给后端分析。这些场景有两个共同点现场没有专职运维定期清理日志故障发生时辅助手段很有限日志文件本身的规律性往往是第一道防线。2.2 为什么不用现成的第三方库有人会问QT 里写日志直接上 spdlog 或 log4qt 不香吗答案是分情况。第三方库成熟、功能多但在这个场景下反而需要做减法。它们有自己的一套格式体系、滚动策略和初始化流程却不知道也不关心上位机界面上的时钟格式更不能天然理解“错误日志单独放一个文件”这种业务语义。真要接进来还得套一层适配层把条件拆分规则翻译给库去执行这层翻译的成本和自研相比并不划算。另一个现实因素是部署环境。客户现场往往禁止引入额外动态库依赖能用一个自包含的源码级模块解决问题就不多带一个 so 或 dll。在这类上位机项目里源码直接编进主程序整个目录拷到设备上就能跑这本身就是验收条件。用 Qt 自带的 QFile、QDir、QDateTime、QMutex 组合起来逻辑完全受自己控制条件判断和文件切换的时机都能按需求微调。后续加字段、加策略也都是在自己的代码上改不用去读第三方库的滚动器源码。2.3 类的划分三个协作者各管一段整体代码不复杂但刻意做了三层拆分避免业务代码和文件细节混成一锅粥。管理类 LoggerManager 是唯一入口承担线程同步和条件调度LoggerFile 负责具体文件的创建、写入、关闭和滚动LoggerConfig 负责从配置文件读取参数并提供默认值。业务层永远只和 LoggerManager 打交道目录路径、文件名规则、滚动条件都封装在内部业务代码里看不到任何与文件相关的细节。调用关系大致是业务线程调用 LoggerManager 的 write 方法 → 加锁 → 判断是否需要滚动 → 如果需要让 LoggerFile 关闭当前文件并打开新文件 → 写入消息 → 按配置决定是否立即 flush。这条链路里最关键的一点是滚动判断发生在写入之前新消息永远进新文件不会出现“本应落在新文件里却写进了旧文件”的错位。对外接口非常简洁核心就是几个宏。下面这段来自 logger_global.h#define LOG_DEBUG LoggerManager::instance().debug #define LOG_INFO LoggerManager::instance().info #define LOG_WARN LoggerManager::instance().warn #define LOG_ERROR LoggerManager::instance().error业务代码只需要包含 logger_global.h然后像用 qDebug 一样调用宏即可内部会转发到管理类的同名方法统一拼装时间戳和级别。宏的好处是调用点短不会在业务方法里引出几行长代码坏处是日志开关完全交给了运行时配置如果哪天想用编译期裁剪还需要再包一层条件宏这个留给二次开发处理。管理类选择单例不是图省事而是这个模块天然需要全局唯一的文件句柄和锁对象。程序里任何一处写日志都必须走同一个实例否则两个实例各持一把锁、各开一个文件进程里日志就直接分家了。C11 之后静态局部变量的初始化是线程安全的instance() 本身没有竞争问题锁只需要保护下面的写路径。职责对照表可以看得更清楚类名对外职责内部核心成员LoggerManager单例入口、线程同步、滚动调度m_mutex、m_file、m_configLoggerFile文件句柄、滚动、写入QFile、QTextStream、m_creationDateLoggerConfig参数装载与默认值QSettings、maxFileSizeBytes、splitByDate3. 核心模块拆解从程序启动到日志自动落盘的完整链路这一章直接踩着代码讲把初始化、滚动判断、写入闭环和三处边界处理都说透。理解了这条链路后面改配置、加策略都会顺手很多。3.1 单例初始化与配置装载业务代码启动时一般在 main() 里做一次初始化int main(int argc, char *argv[]) { QApplication app(argc, argv); LoggerManager::instance().init(config/logger.ini); // ... 业务逻辑 }LoggerManager 的 init 实现大致是这样的void LoggerManager::init(const QString configPath) { QMutexLocker locker(m_mutex); if (m_initialized) { qWarning() logger had been initialized, ignored.; return; } m_configPath configPath.isEmpty() ? defaultConfigPath() : configPath; m_config.load(m_configPath); QDir dir(m_config.logDir); if (!dir.exists()) { dir.mkpath(.); } m_file.reset(new LoggerFile(m_config)); m_file-openCurrentFile(QDateTime::currentDateTime()); m_initialized true; }逻辑说明这里加锁保护初始化过程防止两个线程同时调用 init 导致文件句柄二次打开。m_config.load内部会先写入默认值再尝试从 ini 读取覆盖所以配置文件缺失时不会直接翻车而是按内置参数继续运行。openCurrentFile把打开结果记录在内部成员里后续写入前可以快速检查句柄有效性。参数方面configPath支持相对路径和绝对路径。相对路径以进程工作目录为基准正式发布时建议在 init 里转成绝对路径这样无论从快捷方式还是命令行启动日志落点都是确定的。3.2 条件判断三个维度决定何时切文件滚动判断是整个模块里最核心的逻辑传入即将写入的日志级别返回 true 就表示需要切新文件bool LoggerManager::needsRolling(Level incomingLevel) { if (m_file-size() m_config.maxFileSizeBytes) { return true; } if (m_config.splitByDate m_file-creationDate() ! QDate::currentDate()) { return true; } if (m_config.splitByLevel incomingLevel ! m_file-level()) { return true; } return false; }参数说明incomingLevel是当前这条日志的级别creationDate是文件创建时记录下来的日期一旦跨天必然不等于当天level是当前文件绑定的日志级别在按级别拆分时同一文件只接收同一级别的日志。三个条件之间是“或”关系任何一个成立都会触发滚动。滚动动作封装在rollIfNeeded里void LoggerManager::rollIfNeeded(Level incomingLevel) { if (!m_file-isOpen()) { m_file-openNewFile(QDateTime::currentDateTime()); } else if (needsRolling(incomingLevel)) { m_file-closeAndArchive(); m_file-openNewFile(QDateTime::currentDateTime()); } }这里closeAndArchive并不是单纯 close还会按配置决定是否把旧文件挪到 archive 子目录。对于只按大小分割的场景close 之后再 openNewFile 会自动带上序号避免同名文件互相覆盖。不同配置组合下文件名的形态差别很大日期加级别20240415_error.log、20240415_debug.log日期加大小20240415_001.log、20240415_002.log纯级别error.log、info.log文件名规则建议在项目一开始就定死后续所有归档、清理、跨天判断都围绕这套命名来展开改动命名规则会牵动几乎所有周边逻辑。3.3 写入路径与线程安全写日志的主路径保持简单void LoggerManager::write(Level lv, const QString msg) { QMutexLocker locker(m_mutex); if (!m_initialized) return; rollIfNeeded(lv); QString line formatLine(lv, msg); m_file-writeLine(line); }formatLine 负责把时间戳、级别、线程 ID、消息拼成一行QString LoggerManager::formatLine(Level lv, const QString msg) { return QString([%1][%2][tid:%3] %4) .arg(QDateTime::currentDateTime().toString(yyyy-MM-dd hh:mm:ss.zzz)) .arg(levelName(lv)) .arg(QString::number((quint64)QThread::currentThreadId())) .arg(msg); }逻辑说明整段 write 全程持锁包括滚动判断和文件写入都锁在同一个临界区里。选择大粒度锁是因为滚动和写入是强相关操作如果在滚动判断后放锁另一个线程可能趁虚而入写进旧文件。业务日志写入频率通常不高大粒度锁的竞争可以忽略换来的是绝对安全。这个取舍对日志模块来说是值得的。这里不建议用 QReadWriteLock 做优化因为写操作占绝大多数每次写入都要修改文件偏移量本质还是互斥写读写锁不会带来收益。文件层写入用 QTextStream 包 QFile并在每行后做 flushvoid LoggerFile::writeLine(const QString line) { if (!m_stream.isNull()) { m_stream line \n; m_stream.flush(); } }每次 flush 确实有性能开销但在日志场景里提供两个实际价值一是程序被强杀时最多只丢正在写的那一行而不是缓冲里积压的一批二是日志可以被 tail -f 实时查看现场调试时不用反复重启程序才能看到新输出。等业务写入量真的达到每秒几百条时再改成定时 flush 也不迟。3.4 边界情况时间回拨、写入失败、编码偏差日志系统还会遇到一些平时不起眼、真遇上就懵的情况。时间回拨是其中一个比较隐蔽的问题设备跨时区或者手动校时QDateTime 往回跳如果按日期判断就可能导致文件来回切换产生一堆空文件。一个常见做法是加入幂等判断只有在文件创建日期和新日期确实不同并且当前时间比文件最后写入时间更晚时才触发切换。这样校时造成的抖动不会产生垃圾文件。写入失败要处理的是磁盘满或者权限问题。openNewFile 失败时Manager 不应该反复尝试而是把错误写到 qWarning并把本次写入丢弃掉避免在故障现场再引入新的异常。这里的关键是 openNewFile 返回 false 时write 路径要能安全跳过bool LoggerFile::openNewFile(const QDateTime now) { QString path buildFileName(now); if (m_file.isOpen()) m_file.close(); m_file.setFileName(path); if (!m_file.open(QIODevice::Append | QIODevice::Text)) { qWarning() log file open failed: path m_file.errorString(); return false; } m_stream.setDevice(m_file); return true; }参数说明now是触发打开文件的时间点用于拼进文件名返回 bool 让调用方能判断是否继续写入。如果这里用了 Truncate 模式每次启动都会清空历史日志一定要确认没有误用。编码方面QTextStream 默认按本地编码处理在 Windows 中文环境下写出来的日志可能是 GBK拉到 Linux 上看就乱码。更稳妥的做法是在 LoggerFile 构造函数里显式指定 UTF-8m_stream.setCodec(UTF-8);这样日志文件在任意平台打开都不会出现中文乱码后续做日志上传、入库解析也少一层转换工作。4. 配置驱动改日志分割条件不动一行业务代码4.1 ini 配置项与默认值模块的运行时行为基本都由配置文件驱动这样现场调条件时不需要重新编译。默认配置文件长这样[common] logDir./logs splitByDatetrue splitByLeveltrue maxFileSizeKB5120 flushIntervalMs100 [format] withThreadIdtrue withTimestamptrue timestampFormatyyyy-MM-dd hh:mm:ss.zzz对应 LoggerConfig 里的成员load 时用 QSettings 读取读不到就取默认值。各字段含义如下logDir 是日志根目录splitByDate 开启后文件名带日期splitByLevel 开启后文件名带级别maxFileSizeKB 控制单个文件上限超了就滚动flushIntervalMs 控制定时 flush 的间隔值为 0 表示每次写入立即 flushformat 段控制时间戳和线程号要不要写进日志行。用 QSettings 读 ini 时记得指定 INI 格式否则它会按系统默认格式处理void LoggerConfig::load(const QString path) { QSettings settings(path, QSettings::IniFormat); logDir settings.value(common/logDir, ./logs).toString(); splitByDate settings.value(common/splitByDate, true).toBool(); splitByLevel settings.value(common/splitByLevel, true).toBool(); maxFileSizeBytes settings.value(common/maxFileSizeKB, 5120).toInt() * 1024; flushIntervalMs settings.value(common/flushIntervalMs, 100).toInt(); timestampFormat settings.value(format/timestampFormat, yyyy-MM-dd hh:mm:ss.zzz).toString(); }这里要注意QSettings 对 ini 的小节和键默认用“/”作分隔符所以common/logDir对应 ini 里[common]小节下的 logDir 键。字段名写错不会报错只是会静默读成默认值排查配置问题时要把这点考虑进去。4.2 对外接口业务代码怎么调业务侧看到的接口只有通过宏访问的那几个入口。典型使用方式如下LOG_INFO(device %1 online, ip%2, deviceId, ip); LOG_WARN(temp exceeds threshold: %1, temp); LOG_ERROR(image pipeline failed at frame %1, err%2, frameNo, err);这些宏展开后调用的是模板方法把可变参数拼成一个 QString。模板转发的好处是类型安全传 int、double 时不需要手动转成字符串。对应实现放在头文件里templatetypename... Args void info(const QString fmt, Args... args) { write(Level::Info, formatMessage(fmt, std::forwardArgs(args)...)); }formatMessage 逐次调 QString::arg 完成占位符替换。这里有一个容易被忽略的坑arg 替换是按序执行的如果业务字符串里本身带了“%1”这类字符又刚好和真实参数撞车就会出现替换错位。常见做法是业务侧统一约定文案里不手写数字占位符全部交给接口处理。4.3 集成进 QT 工程的两种方式把 LoggerModule 文件夹放进项目后接入方式有两种。第一种最省事直接在 .pro 里 includeQT core CONFIG console c17 include(LoggerModule/logger.pri)logger.pri 内部把源文件、头文件、包含路径都定义好业务代码只需要 include “logger_global.h”。第二种方式是把日志模块编译成静态库适合在多个业务工程之间复用。需要注意链接的是 Qt5Core 还是 Qt6Core在 .pri 里写清楚否则换个 Qt 版本头文件路径和符号引用都会直接报错。如果项目已经有 QApplication还可以在 init 之后提供一个全局便捷函数 resetConfig()让现场改完配置后不用重启程序。实现思路是按照配置文件重新装载参数并且重建 LoggerFile 对象再重新 open 一次。直接修改 m_config 里某些字段很可能对旧文件失效重建对象是最稳的路径。minLevel 这类过滤需求虽然没有内置到默认配置里但扩展成本很低。在 [common] 段加一个 minLevel2 的字段write 进入主路径前先判断级别是否满足阈值不满足就直接返回能省掉大量无意义的格式化开销。这也是日志模块最常见的一个扩展点。5. 踩坑记录日志模块稳定运行的五个关键细节日志模块的稳定不靠一两行代码靠的是对文件生命周期、线程时序和配置路径的全面控制。下面五个问题我都在真实设备上见过翻车版本有些甚至上线两三个月后才暴露出来。每一条都值得在写完模块后专门写测试用例覆盖。5.1 现象程序被杀后最后几十条日志凭空消失日志文件看起来一切正常但每次用任务管理器强杀进程最后几十条记录就是找不到。问题根源在 QTextStream 的内部缓冲写入文本先落入流缓冲并不会立刻交给操作系统落盘进程被强杀时缓冲内容直接丢弃。解决方法是让 LoggerFile 提供 flush() 并在程序退出路径上调用同时把 flush 间隔变成配置项。我通常会设置默认 100ms 的定时 flushERROR 级别走同步 flush这样既不拖累常规写入也能保证关键信息即时落盘。5.2 现象多线程同时写日志内容串行却又断行两个线程并发写日志时单条日志偶尔被拆成两半中间插入了另一个线程的半行内容日志看起来像被拼错的文本。原因是拼行和写入没有作为一个原子操作业务线程各自调用了 QTextStream而文件偏移量的修改并不是原子操作。解决方法是让所有写入统一经过 LoggerManager 的同一个带锁方法由 QMutexLocker 把整段 write 包括拼行、滚动判断和落盘都保护起来。同样的问题也存在于直接用 fprintf 的场景即使单次 fprintf 在多数平台看起来原子QTextStream 的组合调用也绝不能假设原子。5.3 现象按大小分割后新文件覆盖了旧文件某天单个日志超过 5MB 后继续写后一条日志竟然把前面的内容覆盖掉了一部分。原因通常出在文件名规则上只用了日期加“_new”后缀同一天每次滚动都生成同一个文件名后打开的 Append 模式直接把新内容接在后面业务看起来就像覆盖。解决方法是文件名带滚动序号。每次 openNewFile 前扫描目录里同日期前缀的最大序号序号加一后再创建文件比如生成 20240415_003.log。这里要提醒一点序号判断必须放在 Manager 的锁内否则两个线程同时滚动会生成同一个序号又互相覆盖。5.4 现象跨天时日志时间归属错乱今天的日志进了昨天的文件设备跑过凌晨零点日志的日期明明是今天文件却还是昨天的。常见原因有两个一是只初始化一次m_file 里记录的日期是启动那天的日期跨天判断没有实时刷新二是滚动判断的时机不对比如把日期变化检查放在写入队列之后而不是写入之前。解决方法是每次写入前用 QDateTime::currentDateTime().date() 与当前文件的创建日期做实时比较而不是依赖缓存值。同时坚持滚动动作在写入前执行确保新日志一定进入新文件。5.5 现象日志路径不对翻遍整个目录都找不到日志程序运行正常日志也有内容但运维就是找不到文件。最常见的原因是 logDir 用了相对路径进程工作目录不一致结果就不一样从 IDE 启动时日志在 build 目录从安装目录启动时又落在别处在没有界面的服务程序里尤其难排查。解决方法是 init 时把相对路径标准化成绝对路径并用 qInfo 打印一次实际落盘路径。更进一步的方案是在程序设置界面里展示这样现场点一下就能直达目录。这个细节看上去小实际是现场反馈里出现频率最高的“日志玄学”之一。6. 二次开发给日志模块加上归档清理和异步队列默认实现里日志写入是同步阻塞的每条日志都要进锁并操作文件日志量上来之后会挤占业务线程。改造的第一步通常是加一个异步队列业务线程把格式化好的日志行推入 QQueue另一个工作线程统一消费批量落盘。队列长度要做上限保护消息积压过多时优先丢弃 DEBUG保证 ERROR 一定进队列。这里要特别注意跨天判断和滚动必须在消费线程里做否则队列里的日志归属会乱掉先来后到关系会对不上。第二件值得做的事是归档与定期清理。默认实现目前会无限保留文件对长期运行的设备不健康。可以增加 keepDays 配置项日志滚动或每次启动时扫描日志目录把超过保留期的 .log 文件移动或删除。归档子目录按月份组织运维只需要关注最近几天时直接看根目录即可。第三件建议增加的是进程启动标记每次启动在日志里打一条包含程序版本、启动时间、配置文件路径的记录。设备如果重启过很多次排查问题的第一个人手动作会轻松很多。改造完的验证步骤也不复杂先用脚本或手工改系统时间模拟跨天再用多线程压测循环连续写几千条日志最后检查文件数量、每条日志完整性和跨天归属。我自己动手时习惯把文件命名规则当作接口约束先定死后面所有功能都围绕这套命名展开避免各模块各写一套。这次拆解日志模块我也保持了同样的习惯条件清单先列出来再动代码。从那以后我每次接 QT 日志需求都强制先过一遍日期、级别、大小这些边界条件再用这份代码结构搭建日志路径目录清爽现场排查也少了很多来回。希望帮到你。本文还有配套的精品资源点击获取
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
