深入浅出 Loguru：
让 Python 日志优雅到飞起
还在用 print() 调试、用 logging 被配置劝退？Loguru 会让你明白：打日志原来可以这么简单又好看。
一、为什么需要 Loguru？print 不香吗？
print() 调试在脚本短小的时候确实顺手，但一旦项目变大，它就暴露出一堆问题：分不清正常运行还是出错、没有时间戳、上了生产没法关掉、报错时看不到完整堆栈。等到你想"正经"打日志，不少人会去翻标准库 logging，结果被 logger、handler、formatter、filter 一套组合拳劝退。
Loguru 是 Python 社区里最受欢迎的现代日志库（GitHub 星标 1.9 万+，月下载量数千万），由 Delgan 打造。它把"开箱即用"做到了极致：不需要任何配置就能输出带颜色、带时间、带文件行号的漂亮日志，写文件、滚动切割、异常捕获全自动。
🎯 零配置上手 — from loguru import logger 直接用，没有 handler/formatter 的繁琐 setup。
📝 自动彩色与上下文 — 时间、级别、文件、行号、函数名全自动附带，终端里花花绿绿一目了然。
🪣 文件与滚动切割 — 一行 add() 就能写文件，还能按大小/时间自动切分、压缩、保留最近 N 份。
一句话总结：Loguru = logging 的"傻瓜相机"版本。你要的它都默认帮你做好，需要进阶时又随时能精细控制。
二、安装与第一个彩色日志
安装只需一行：
无需任何配置，直接感受 Loguru 的威力：
from loguru import logger
logger.debug("这是一条调试信息")
logger.info("服务启动成功 ✅")
logger.warning("磁盘空间不足 20%")
logger.error("数据库连接失败！")
logger.success("任务全部完成")
运行后你会看到：每条日志前面自动带上了时间、级别（带颜色）、文件名:行号:函数名。INFO 是白色、SUCCESS 是绿色、WARNING 是黄色、ERROR 是红色——眼睛一下就能抓住重点。完全不需要像 logging 那样先配 basicConfig。
💡 小技巧：Loguru 的 logger 是个全局单例，任何模块里 from loguru import logger 拿到的都是同一个对象，配置一次全局生效。
三、核心 API：logger 与日志级别
Loguru 内置 7 个级别，从低到高：TRACE(5) < DEBUG(10) < INFO(20) < SUCCESS(25) < WARNING(30) < ERROR(40) < CRITICAL(50)。注意它比标准库多了 TRACE 和 SUCCESS 两个级别，非常实用。
用 logger.level() 控制显示门槛——低于该级别的日志不会输出：
from loguru import logger
logger.remove() # 清空默认 handler
logger.add(sys.stderr, level="INFO") # 只显示 INFO 及以上
logger.debug("看不见我") # 被过滤
logger.info("能看到我") # 输出
日志还支持 结构化参数，用大括号占位，比 f-string 更安全（生产环境关闭时不会做无谓拼接）：
user = "Alice"
logger.info("用户 {} 登录成功", user)
logger.bind(order_id=1024).info("订单处理中")
四、写文件 + 自动滚动切割（最爽的功能）
标准库要写文件、按大小切割，得配 RotatingFileHandler 或 TimedRotatingFileHandler，代码又臭又长。Loguru 一行搞定：
from loguru import logger
# 写入 app.log，超过 10MB 自动切一个新文件，最多保留 3 份并压缩
logger.add(
"app.log",
rotation="10 MB",
retention=3,
compression="zip",
encoding="utf-8",
enqueue=True, # 异步写入，不阻塞主线程
backtrace=True, # 记录完整异常链
diagnose=True, # 显示变量值，便于排错
)
几个关键参数：
rotation — 切割触发条件："500 MB"、"1 week"、"00:00"（每天零点）、甚至一个回调函数。
retention — 保留策略："10 days"、5（保留最新 5 个文件）。
enqueue=True — 强烈推荐！日志写入放到独立线程，Web 服务高并发时不会拖慢接口响应。
五、自定义日志格式
默认格式已经很够用，但想要 JSON 格式（方便 ELK、Loki 等日志系统收集）也很容易：
import sys, json
from loguru import logger
def json_sink(message):
record = message.record
line = {
"time": record["time"].isoformat(),
"level": record["level"].name,
"msg": record["message"],
"file": record["file"].name,
}
sys.stdout.write(json.dumps(line, ensure_ascii=False) + "\n")
logger.add(json_sink, level="INFO")
logger.info("订单创建 {}", 1024)
也可以直接用 format 参数定制字符串模板，{time}、{level}、{message} 等占位符随手拈来。
六、异常捕获神器：@logger.catch 装饰器
这是 Loguru 最让人"上头"的功能。传统做法要给函数包一层 try/except，还要手动 logger.exception()。Loguru 只要一个装饰器：
from loguru import logger
@logger.catch
def divide(a, b):
return a / b
divide(1, 0) # 崩溃了吗？不，异常被捕获并打印出漂亮的完整堆栈
被装饰的函数一旦抛异常，Loguru 会用带语法高亮、带变量值的精美回溯打印出来，而且默认不会让程序挂掉（异常被吞掉）。若想让它照常抛出，加 @logger.catch(reraise=True)。
七、分级与过滤：不同模块不同策略
真实项目里，你往往希望"支付模块打 DEBUG，第三方库只打 WARNING"。用 filter 轻松实现：
# 只接收来自 payment 模块的日志
logger.add("pay.log", filter=lambda r: r["extra"].get("module") == "payment")
pay_logger = logger.bind(module="payment")
pay_logger.debug("支付请求签名完成") # 进入 pay.log
logger.debug("其他模块日志") # 不会进 pay.log
bind() 还能给日志附加任意上下文字段（如 user_id、request_id），排查问题时事半功倍。这是 logging 用起来很别扭、Loguru 一行就解决的典型场景。
八、实战：在 FastAPI 项目里集成 Loguru
结合我们之前讲过的 FastAPI，一个生产可用的日志配置长这样：
# logger_config.py
import sys
from loguru import logger
logger.remove() # 关掉默认 handler
logger.add(
sys.stdout,
level="INFO",
colorize=True,
format="<green>{time:YYYY-MM-DD HH:mm:ss}</green> | "
"<level>{level:<8}</level> | "
"<cyan>{name}</cyan>:{function}:{line} - <level>{message}</level>",
)
logger.add(
"logs/api.log",
rotation="00:00",
retention="14 days",
compression="zip",
encoding="utf-8",
enqueue=True,
backtrace=True,
diagnose=True,
)
然后在 FastAPI 里用它替代 print 和 uvicorn 自带的日志即可。配合前面学过的 Pydantic 校验、httpx 请求，一套现代 Python 后端的技术栈就齐活了。
九、新手最常踩的 3 个坑
1. 忘记 remove() 导致重复输出：多次 add() 同类型 handler 会让日志打印两遍。要么只配一次，要么先 remove() 再 add()。
2. 高并发忘了 enqueue=True：Web 服务里日志写入会阻塞请求线程，务必开启异步队列写入。
3. 和 logging 混用：若第三方库用标准库 logging，用 logger = logger.patch(...) 或 loguru 的 intercept 方案把 logging 桥接到 loguru，避免两套输出混乱。
十、总结：Loguru 速查表
| 需求 |
Loguru 写法 |
| 打印彩色日志 |
logger.info("hi") |
| 写文件+滚动切割 |
logger.add("a.log", rotation="10 MB") |
| 捕获函数异常 |
@logger.catch |
| 附加上下文 |
logger.bind(user="Alice") |
| 异步不阻塞 |
logger.add(..., enqueue=True) |
一句话总结：Loguru 让你用近乎零的成本，获得生产级日志能力——彩色输出、文件滚动、异常神捕获、上下文绑定，每一项都直击痛点。新项目直接 pip install loguru，基本不会后悔。它和前面讲过的 FastAPI、Pydantic、httpx 同属现代 Python 后端"标配四件套"，强烈建议一起学。
🚀 立即行动
pip install loguru → 把 print 换成 logger → 加一个写文件+滚动的 handler → 用 @logger.catch 包裹易错函数。
Loguru 官方文档：https://loguru.readthedocs.io/（含完整 API 与示例）
— END —
关注我们，每周一个 Python 热门技术实战教程
