Loguru：Python 日志的零配置方案

Loguru：Python 日志的零配置方案

写 Python 的人几乎都踩过标准库 logging 的坑。配置繁琐，Handler、Formatter、Filter 层层嵌套，代码还没开始写，日志配置先占几十行。不少人干脆放弃，直接用 print() 应付。Loguru 就是来解决这个问题的，目前它在 GitHub 上收获了 23,935 个 Star。

核心思路：一个 logger 走到底

Loguru 的设计理念很简单，只暴露一个全局 logger，预配置好默认输出到 stderr。最简单的用法就两行：

from loguru import logger
logger.debug("That's it, beautiful and simple logging!")

不需要创建 Logger 实例，不用配 Handler，不用写 Formatter。想用文件日志，直接传路径字符串：

logger.add("file.log")

所有高级功能都收敛到 add() 这一个函数里。过滤、格式化、级别控制，都是参数的事。logger.remove() 可以清掉默认 handler，从零开始自定义。

文件日志和格式化

文件日志支持按大小、时间、周期自动轮转，还能自动压缩旧文件：

logger.add("file.log", rotation="500 MB")
logger.add("file.log", retention="10 days")
logger.add("file.log", compression="zip")

格式字符串用花括号 {}，跟 Python 的 str.format() 一致，告别 %s 的老式写法。时间格式也可以完全自定义，比如 {time:YYYY-MM-DD at HH:mm:ss}。

异常处理方面，@logger.catch 装饰器可以捕获线程内或主线程的异常，保证错误一定能被记录下来。开启 backtrace 和 diagnose 后，异常堆栈会带上每一层变量的实际值，排查问题快很多。

几个实用的细节

结构化日志用 serialize=True 可以把每条日志转成 JSON，方便后续解析和收集。bind() 方法可以给日志附加自定义字段，比如用户 ID、IP 地址，做上下文追踪很顺手。contextualize() 还能在代码块级别临时注入上下文，出了作用域自动恢复。

性能敏感的场景可以用 opt(lazy=True)，只在日志级别满足条件时才执行昂贵的格式化函数，避免不必要的开销。

线程安全是默认的，多进程场景加上 enqueue=True 就能保证日志顺序不混乱。协程函数作为 sink 也支持，配合 complete() 等待所有日志落盘，异步项目里同样能用。

如果你之前项目里已经用了标准库的 logging，Loguru 提供了兼容方案，可以双向桥接，迁移成本很低。

适合谁用

如果你受够了 logging 的样板代码，想要一个开箱即用的方案，Loguru 很合适。它的 API 设计直观，文档也清晰，从脚本到大型项目都能覆盖。

对于写库的作者，Loguru 提供了 disable() 机制，默认静默，由调用方决定是否开启，避免污染用户的日志输出。

整体来说，Loguru 把 Python 日志从"需要专门学一套配置"变成了"导入就能用"，这个体验提升很实在。两万多的 Star 说明有同样痛点的人不在少数。