Loguru 基础教程

loguru 是 Python 最好用的日志库之一，几乎零配置、语法优雅、功能强大，比标准库 logging 简单很多。

1. 📦 安装

pip install loguru

2. 🚀 快速上手

from loguru import logger

logger.info("Hello, Loguru!")

运行直接输出：

2025-11-30 18:19:10.123 | INFO  | __main__: <module>: 3 - Hello, Loguru!

默认就带时间、级别、文件名、行号。

3. 📝 基本用法示例

3.1 日志级别

Loguru 默认支持：

trace（比 debug 更细）
debug
info
success（loguru 特有）
warning
error
critical

logger.debug("调试信息")
logger.info("一般信息")
logger.success("成功提示")
logger.error("错误提示")

4. 🎨 自定义日志格式

logger.add("app.log",
           format="{time:YYYY-MM-DD HH:mm:ss} | {level} | {message}")

你可以自定义字段：

{time}
{level}
{message}
{file}
{line}
{function}
{process}
{thread}

5. ✨ 添加文件日志（自动切割、压缩）

Loguru 的杀手级功能之一：自动按大小、时间切割 + 自动保留数量 + 自动压缩

5.1 按大小切割

logger.add("app.log", rotation="10 MB")

5.2 按日期切割

logger.add("app.log", rotation="00:00")  # 每天零点生成新日志

5.3 按时间间隔切割

logger.add("app.log", rotation="1 week")

5.4 自动压缩与保留

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

说明：

retention：日志保存时间
compression：“zip”/“gz”/“bz2”/“xz”

6. 🔍 日志输出到多目标（终端 + 文件）

logger.add("app.log")
logger.info("这条会同时打印到终端和文件")

7. 🔥 捕获异常堆栈

非常爽的功能：

@logger.catch
def main():
    1 / 0

main()

效果：自动打印完整 traceback，不需要再写 try/except。

如果你想自定义级别：

@logger.catch(level="ERROR")
def run():
    pass

8. 🧩 与标准 logging 兼容（FastAPI 等场景必备）

很多框架（如 FastAPI、uvicorn）内部用标准库 logging。

你可以拦截它们，统一用 loguru：

import logging
from loguru import logger
import sys

class InterceptHandler(logging.Handler):
    def emit(self, record):
        logger_opt = logger.opt(depth=6, exception=record.exc_info)
        logger_opt.log(record.levelname, record.getMessage())

logging.basicConfig(handlers=[InterceptHandler()], level=0)
logger.add(sys.stdout, level="INFO")

FastAPI 可直接整合。

9. 📁 按模块动态创建日志（生产环境常用）

logger.add("logs/{time:YYYYMMDD}/{level}.log",
           rotation="1 day",
           retention="7 days")

效果：

logs/20251130/INFO.log
logs/20251130/ERROR.log
...

10. 🧵 同步 + 异步安全

Loguru 本身线程安全，也能用于 multiprocessing，但需要注意：

logger.add("app.log", enqueue=True)

enqueue=True 使用队列，保证多进程环境不会日志错乱。

11. 🔧 生产环境推荐配置（直接用）

from loguru import logger
import sys

logger.remove()  # 移除默认控制台输出

logger.add(sys.stdout,
           level="INFO",
           format="<green>{time:YYYY-MM-DD HH:mm:ss}</green> "
                  "| <level>{level}</level> "
                  "| <cyan>{name}</cyan>:<cyan>{line}</cyan> "
                  "- <level>{message}</level>")

logger.add("logs/app.log",
           rotation="100 MB",
           retention="14 days",
           compression="zip",
           enqueue=True,
           encoding="utf-8")

logger.success("Loguru 初始化完毕！")

这套配置适用于：

FastAPI
Flask
Django
定时任务脚本
后端服务
Docker 生产部署

12. 📚 更多高级功能

📌 动态过滤不同级别日志到不同文件

logger.add("error.log", level="ERROR")
logger.add("info.log", filter=lambda r: r["level"].name == "INFO")

📌 延迟写入（减少 IO）

logger.add("app.log", buffer_size=1024)