1. 为什么值得自己动手写一个日志类

刚入行那会儿，我对日志这件事的态度特别敷衍——需要输出信息就printf，需要写文件就fopen加fprintf，项目里到处都是散落的打印语句，出了问题就靠肉眼在终端里翻。直到有一次线上环境跑了一周，某个模块偶发崩溃，我打开日志文件一看，几万行输出混在一起，没有时间戳、没有级别、没有模块标识，连哪一行是错误都分不清。那次排查花了整整两天，最后定位到的问题其实很小，但因为没有结构化的日志，硬生生把十分钟的事拖成了两天。

从那以后我就下定决心，自己动手写一个够用、可控、不依赖第三方库的日志类。C++ 标准库本身没有日志设施，第三方库虽然成熟，但在一些嵌入式场景、教学项目、或者对二进制体积敏感的环境里，引入一个庞大的依赖并不划算。自己写一个轻量级的日志类，代码量不大，却能彻底搞清楚日志系统到底在做什么，出了问题也能自己改。

这篇文章要聊的，就是怎么用 C++ 从零实现一个简单但实用的日志类。它需要满足几个基本诉求：支持日志级别过滤、支持输出到控制台和文件、支持格式化输出、线程安全、使用起来足够顺手。适合有一定 C++ 基础、想搞清楚日志系统内部原理、或者需要一个轻量方案的朋友。我不会一上来就甩一大段代码，而是先把设计思路讲透，再一步步落地，最后把踩过的坑和排查经验一并交出来。

2. 日志类的整体设计与思路拆解

2.1 先想清楚：一个日志类到底要解决什么问题

很多人写日志类，第一反应是"我要把信息打印出来"。这个理解太浅了。日志系统的本质是在程序运行过程中，按时间顺序记录下发生了什么，并且让这些记录在事后能够被高效地检索和分析。所以它要解决的核心问题不是"打印"，而是"记录"和"检索"。

基于这个认知，一个合格的日志类至少要处理四件事。第一是分级，不同信息的重要性天差地别，调试信息、普通流程信息、警告、错误，它们的处理策略应该不同，生产环境不该输出海量调试信息。第二是格式化，日志里必须包含时间、级别、文件、行号这些上下文，否则事后根本不知道这条日志从哪来。第三是输出目标，开发时想看控制台，上线后要落盘到文件，最好还能同时输出。第四是并发安全，多线程环境下多个线程同时写日志，如果不加锁，输出内容会互相穿插，日志直接变成乱码。

把这四件事想明白，类的接口设计基本就定型了。我见过不少人一上来就写代码，写着写着发现要加时间戳得改一堆地方，要加文件输出又得重构，就是因为没先把需求拆清楚。

2.2 方案选型：为什么不用现成的库

这里得说清楚一个取舍问题。市面上成熟的日志库不少，功能强大、性能优秀，那为什么还要自己写？我的判断标准是这样的：如果你的项目规模大、对日志性能有极致要求、需要日志轮转和异步落盘这些高级特性，那用成熟库是明智的，没必要重复造轮子。但如果你是在学习阶段、项目体量小、或者运行环境受限（比如某些嵌入式平台、教学演示、算法竞赛的调试工具），自己写一个几百行的日志类反而更合适。

自己写的优势在于完全可控。你知道每一行代码在干什么，出问题能立刻定位，想加个自定义字段、改个输出格式，改几行就行，不用去翻别人的文档和源码。而且写一遍之后，你对日志系统的理解会上一个台阶，以后用任何第三方库都能快速上手。

我这次的方案是单例模式 + 宏封装 + 流式接口。单例保证全局只有一个日志实例，避免多个实例争抢文件句柄；宏封装是为了自动捕获文件名和行号，这是__FILE__和__LINE__的用武之地；流式接口则是模仿std::cout的用法，让调用方写起来自然。这个组合是业界非常常见的做法，兼顾了易用性和可控性。

2.3 核心结构设计：几个关键组件的职责划分

在动手之前，先把类的内部结构规划好。我把它拆成几个部分。

日志级别枚举，定义 DEBUG、INFO、WARN、ERROR 这几个常见级别，用枚举而不是宏，类型更安全。日志消息结构体，用来承载一条日志的所有信息——时间戳、级别、文件名、行号、正文内容。格式化器，负责把消息结构体转成最终要输出的字符串。输出器，负责把格式化后的字符串写到控制台或文件。日志类主体，对外提供接口，内部管理级别过滤、输出目标、线程锁。

这种拆分的好处是职责清晰。比如以后想加一个"输出到网络"的功能，只需要新增一个输出器，其他部分不用动。想改时间格式，只动格式化器。这就是所谓的开闭原则在实际项目里的体现——对扩展开放，对修改关闭。

提示：不要一上来就追求大而全的设计。我见过有人为了"可扩展"把日志类设计成十几个类互相继承，结果一个简单的日志功能写了上千行，维护成本反而更高。简单场景下，够用就好，等真的需要扩展时再重构也不迟。

3. 核心细节解析与实操要点

3.1 日志级别的设计：枚举与过滤逻辑

级别设计看起来简单，其实有讲究。我用一个枚举来定义：

enum class LogLevel { DEBUG = 0, INFO = 1, WARN = 2, ERROR = 3 };

用enum class而不是普通enum，是为了避免命名污染和隐式类型转换。数值从 0 到 3 递增，这样过滤逻辑就非常直观——只有级别大于等于当前设定阈值的日志才会被输出。比如阈值设为 INFO（1），那么 DEBUG（0）就被过滤掉，INFO、WARN、ERROR 都会输出。

这个"大于等于"的设计是关键。很多人会写成"等于"，结果设了 WARN 级别后，ERROR 反而不输出了，这就是逻辑没想清楚。级别是有序的，高等级天然应该包含低等级的严重性。

过滤判断放在日志类的入口处，越早判断越好，避免做无谓的字符串拼接和格式化。这一点在性能敏感的场景下很重要——如果一条 DEBUG 日志最终会被过滤掉，那它连参数都不该被求值。这也是为什么后面要用宏来做惰性求值的原因。

3.2 时间戳获取：跨平台的那些坑

时间戳是日志的灵魂，没有时间戳的日志基本没有排查价值。C++ 里获取时间有好几种方式，我选的是std::chrono配合std::time_t，兼顾精度和可读性。

auto now = std::chrono::system_clock::now(); std::time_t t = std::chrono::system_clock::to_time_t(now); auto ms = std::chrono::duration_cast<std::chrono::milliseconds>( now.time_since_epoch()) % 1000;

这里有个大坑：std::localtime不是线程安全的，它返回一个指向静态缓冲区的指针，多线程同时调用会互相覆盖。解决办法是用localtime_r（POSIX）或者localtime_s（Windows），或者干脆自己加锁。我为了跨平台，封装了一个小函数，用条件编译区分平台。

毫秒部分用duration_cast取出来，再对 1000 取模，就得到当前秒内的毫秒数。格式化的时候补零到三位，这样时间戳看起来整齐，排序也方便。别小看这个补零，我见过日志里时间戳一会儿9:5:3一会儿10:15:30，肉眼比对时特别费劲。

注意：std::chrono::system_clock受系统时间调整影响，如果程序运行期间系统时间被改（比如 NTP 同步），日志时间戳可能出现回退。对时间单调性有要求的场景，可以考虑用steady_clock记录相对时间，再配合启动时的绝对时间换算。

3.3 文件名与行号的自动捕获

这是宏封装存在的最大理由。如果靠函数参数传文件名和行号，调用方每次都得手写__FILE__和__LINE__，既啰嗦又容易漏。用宏就优雅多了：

#define LOG_DEBUG(msg) \ Logger::getInstance().log(LogLevel::DEBUG, __FILE__, __LINE__, msg)

__FILE__和__LINE__是预处理器提供的，在宏展开的位置自动替换成当前文件名和行号，调用方完全无感。这就是为什么日志接口几乎都用宏而不是普通函数。

不过__FILE__有个小问题：它通常是完整路径，可能很长，日志里显得臃肿。我一般会在运行时截取最后一个路径分隔符之后的部分，只保留文件名。这样日志更清爽，也避免了暴露项目的目录结构。

const char* shortName(const char* path) { const char* p = strrchr(path, '/'); const char* q = strrchr(path, '\\'); const char* last = p > q ? p : q; return last ? last + 1 : path; }

同时处理/和\\是为了跨平台，Windows 用反斜杠，类 Unix 用正斜杠。

3.4 流式接口的实现：让日志写起来像 cout

std::cout的链式调用用起来很舒服，日志类也可以模仿。核心是重载operator<<，返回自身的引用，这样就能一直链下去。

class LogStream { public: LogStream(LogLevel level, const char* file, int line); ~LogStream(); // 析构时真正输出 template<typename T> LogStream& operator<<(const T& value) { buffer_ << value; return *this; } private: std::ostringstream buffer_; LogLevel level_; const char* file_; int line_; };

这里有个非常巧妙的设计：在析构函数里输出。因为一条日志语句LOG_INFO << "x=" << x;执行完，临时对象LogStream就析构了，此时缓冲区里已经攒齐了所有内容，正好一次性输出。这个技巧叫 RAII（资源获取即初始化），是 C++ 里非常经典的模式。

用std::ostringstream做缓冲区，好处是它能自动处理各种类型的转换——整数、浮点、字符串、甚至重载了operator<<的自定义类型，全都能塞进去。比自己写类型判断省事太多。

提示：析构函数里做输出，一定要保证不抛异常。如果输出过程中出错（比如磁盘满了），异常从析构函数抛出会导致程序直接终止。所以输出逻辑内部要 try-catch 兜底，出错就静默处理或者写个备用通道。

4. 实操过程与核心环节实现

4.1 单例模式的落地：线程安全的懒汉式实现

日志类全局唯一，单例是最自然的选择。但单例的线程安全是个经典话题。C++11 之后，局部静态变量的初始化是线程安全的，这给了我们一个非常简洁的写法：

class Logger { public: static Logger& getInstance() { static Logger instance; return instance; } Logger(const Logger&) = delete; Logger& operator=(const Logger&) = delete; private: Logger() = default; };

这个写法叫Meyers Singleton，是 C++ 里最推荐的懒汉式单例。局部静态变量instance在第一次调用getInstance时才构造，而且 C++11 标准保证这个构造过程是线程安全的，编译器会自动加锁。比手动写双重检查锁定（DCLP）简洁得多，也不容易出错。

删除拷贝构造和赋值运算符是必须的，否则别人可以Logger a = Logger::getInstance();复制出一个新实例，单例就破了。用= delete显式禁用，编译期就能拦住。

4.2 输出目标的切换：控制台与文件双通道

输出目标我设计成可配置的。内部维护两个标志位，一个表示是否输出到控制台，一个表示是否输出到文件。文件输出用一个std::ofstream成员管理。

void Logger::setConsoleOutput(bool enable) { console_ = enable; } void Logger::setFileOutput(const std::string& filename) { if (fileStream_.is_open()) fileStream_.close(); fileStream_.open(filename, std::ios::app); fileOutput_ = fileStream_.is_open(); }

文件用std::ios::app追加模式打开，这样程序重启后不会覆盖之前的日志，历史记录得以保留。这一点很重要，我踩过坑——有次用默认模式打开，程序崩溃重启后把之前的日志全冲掉了，正好丢掉了崩溃前的关键信息。

输出的时候，先格式化成一个完整字符串，然后分别往两个通道写。控制台用std::cout，文件用fileStream_。两个通道都写完后，记得flush，尤其是文件流。因为ofstream有缓冲区，如果程序异常退出，缓冲区里的内容可能还没落盘，日志就丢了。对 ERROR 级别的日志，我一般强制立即 flush，确保关键信息不丢。

4.3 线程安全：一把锁解决并发写冲突

多线程写日志，不加锁必然出问题。两个线程同时往std::cout写，输出会交错成[IN[INFO]FO]这种鬼样子。解决办法是在输出环节加一把互斥锁。

std::mutex mutex_; void Logger::output(const std::string& line) { std::lock_guard<std::mutex> lock(mutex_); if (console_) { std::cout << line << std::endl; } if (fileOutput_) { fileStream_ << line << std::endl; fileStream_.flush(); } }

用std::lock_guard而不是手动lock/unlock，是为了保证异常安全——即使中间抛异常，锁也能自动释放，不会死锁。这是 RAII 的又一次应用。

锁的粒度要控制好。我只在最终输出时加锁，格式化过程在锁外完成。如果把整个日志构造过程都锁住，并发性能会大幅下降。日志系统本身不该成为程序的性能瓶颈。

注意：如果日志量非常大，锁竞争会很激烈。这时候可以考虑异步日志——用一个队列把日志消息传给后台线程，前台只管入队。但异步日志复杂度高，涉及队列满时的丢弃策略、程序退出时的 flush 等问题，简单场景下不建议上。

4.4 完整调用示例与效果验证

把上面的部分拼起来，一个可用的日志类就成型了。调用方式是这样的：

LOG_DEBUG << "进入函数，参数 x=" << x; LOG_INFO << "处理完成，耗时 " << ms << " ms"; LOG_WARN << "缓存命中率偏低：" << rate; LOG_ERROR << "打开文件失败：" << filename;

输出效果大致是：

[2024-06-15 14:23:01.123] [INFO ] [main.cpp:42] 处理完成，耗时 15 ms [2024-06-15 14:23:01.456] [WARN ] [main.cpp:43] 缓存命中率偏低：0.32 [2024-06-15 14:23:01.789] [ERROR] [main.cpp:44] 打开文件失败：data.txt

时间戳、级别、文件行号、正文，四要素齐全，对齐整齐，一眼就能扫出关键信息。级别用固定宽度（INFO补空格到 5 位），是为了让方括号对齐，视觉上更舒服。

验证的时候，我建议写个小测试：开几个线程，每个线程循环打一万条日志，看看输出有没有交错、有没有丢失、程序退出后文件内容是否完整。这个测试能同时验证线程安全和 flush 逻辑，非常值得做。

5. 常见问题与排查技巧实录

5.1 日志丢失：缓冲区没刷新是头号嫌疑

日志丢失是最常见的问题，表现是程序崩溃后，日志文件里看不到崩溃前最后几条记录。原因几乎都是缓冲区没 flush。ofstream和cout都有缓冲区，数据先写到内存缓冲区，攒够一定量或者遇到换行才真正落盘。程序如果异常终止（比如段错误），缓冲区里的内容就永远丢了。

解决办法有两个。一是每条日志都 flush，简单粗暴但性能有损耗，适合日志量不大的场景。二是只对 WARN 和 ERROR 级别强制 flush，普通日志靠缓冲区攒着，兼顾性能和可靠性。我一般用第二种，因为真正需要确保不丢的就是错误信息。

排查这类问题时，可以在输出后立刻检查文件内容，如果发现文件里少了几条，基本就是 flush 的问题。另外，程序正常退出时，ofstream的析构函数会自动 flush，所以正常退出的日志通常是完整的，只有异常退出才会丢。

5.2 输出乱码或交错：锁没加对地方

多线程下日志交错，说明锁没覆盖到完整的输出操作。常见错误是只锁了cout没锁文件流，或者格式化在锁外、输出在锁内导致两条日志的格式化结果互相覆盖。

排查方法是把锁的范围画出来，确认从"决定要输出"到"输出完成"这整段都在锁内。另一个隐蔽的坑是，如果用了std::endl，它本身会 flush，而 flush 是个相对慢的操作，锁持有时间变长，竞争加剧。可以考虑用'\n'代替std::endl，把 flush 时机控制在自己手里。

还有一种情况是日志内容本身乱码，那多半是编码问题——源文件是 UTF-8，控制台是 GBK，中文就花了。这种跟日志类无关，是终端编码设置的问题，换个支持 UTF-8 的终端或者统一编码即可。

5.3 性能问题：日志拖慢了主流程

日志写多了确实会拖慢程序，尤其是同步写文件。我做过一个粗略测试，同步写文件的情况下，每条日志大概几十微秒，如果一秒钟打几万条，光日志就吃掉大量 CPU。

优化的思路有几个。第一是级别过滤前置，DEBUG 日志在生产环境直接关掉，连字符串拼接都不做。第二是减少 flush 频率，非关键日志攒着批量写。第三是异步化，把写操作丢给后台线程。第四是精简格式，时间戳精确到秒而不是毫秒，能省一点格式化开销。

不过要提醒一句，优化之前先测量。很多人凭感觉觉得日志慢，实际上瓶颈在别处。用性能分析工具定位一下，确认日志真的是热点再动手，别过早优化。

5.4 常见问题速查表

这张表是我这些年实际遇到过的典型问题汇总，基本覆盖了自研日志类 90% 的故障场景。遇到问题先对号入座，能省不少排查时间。

5.5 几个容易被忽略的实操心得

第一个心得是日志文件要能轮转。哪怕是最简单的实现，也建议加一个按大小切分的逻辑——文件超过比如 10MB 就换个新文件。否则程序跑久了，日志文件能涨到几个 G，打开都费劲。轮转逻辑不复杂，写之前检查文件大小，超了就改名重开。

第二个心得是给日志加个进程标识。如果同时跑多个实例，日志混在一起很难区分。在每条日志里带上进程 ID，或者干脆每个实例写不同的文件，排查时能省很多事。

第三个心得是别在日志里打敏感信息。密码、密钥、用户隐私这些，一旦写进日志文件，就是个安全隐患。我一般会在日志类里加一个简单的脱敏开关，或者至少在代码审查时重点盯这类调用。

第四个心得是日志级别要动态可调。开发时想看 DEBUG，上线后想只看 WARN，如果级别是编译期写死的，改一次就得重新编译。做成运行时可配置（读配置文件或环境变量），灵活性高很多。

6. 从简单实现到生产可用的演进方向

一个几百行的日志类，应付日常开发和中小项目绰绰有余。但如果要往生产级靠，还有几个方向可以演进。

异步日志是性能提升最明显的一步。核心思路是前台线程只负责把日志消息塞进一个线程安全队列，后台线程专门负责格式化、写文件。这样前台几乎不阻塞，日志对主流程的影响降到最低。代价是要处理队列满时的策略（丢弃还是阻塞）、程序退出时的 flush 顺序，复杂度上了一个台阶。

日志轮转与归档是运维友好的关键。按天切分、按大小切分、保留最近 N 个文件、自动压缩旧文件，这些功能能让日志管理省心很多。实现上就是文件操作加一点定时逻辑，不难但很实用。

结构化日志是另一个趋势。把日志输出成 JSON 格式，每条日志是一个 JSON 对象，字段清晰，方便被日志采集系统解析和检索。相比纯文本，结构化日志在自动化分析场景下优势明显。

多目标输出也值得考虑。除了控制台和文件，还可以输出到系统日志、调试窗口、甚至通过网络发送到集中式日志服务器。前面说的输出器拆分设计，在这里就体现出价值了——新增一个输出目标，只需要加一个输出器类，主体逻辑不用动。

我个人在实际项目里的体会是，日志类的复杂度应该和项目规模匹配。小项目别过度设计，够用就行；大项目则要提前规划好轮转、异步、结构化这些能力，否则后期改造的成本会很高。最忌讳的是既想要简单又想要全能，结果写成一个四不像，既不好用也不好维护。

最后再分享一个小技巧：给日志类写一套单元测试，覆盖级别过滤、格式化、并发写入、文件轮转这几个核心场景。日志系统本身如果出问题，排查起来特别痛苦，因为它往往是在最需要它的时候掉链子。花点时间把测试补上，长期看绝对划算。