loguru 用法

loguru 是一个 Python 的第三方日志库，相比标准库中的 logging 模块，它设计更加简洁、易用，功能强大，支持结构化日志、异步日志、颜色输出、自动文件分割、压缩等功能。

以下是 loguru 的基本用法和常见功能：

---

1. 安装

bash

深色版本

pip install loguru

---

2. 基本使用

loguru 的 logger 是开箱即用的，无需配置即可直接使用：

python

深色版本

from loguru import logger
logger.debug("这是一个调试信息")

logger.info("这是一个普通信息")

logger.warning("这是一个警告")

logger.error("这是一个错误")

logger.critical("这是一个严重错误")

默认情况下，loguru 会将 INFO 及以上级别的日志输出到控制台，并自动着色。

---

3. 添加日志文件输出

使用 logger.add() 将日志写入文件：

python

深色版本

# 写入到文件，每天一个文件，保留7天
logger.add("app.log", rotation="1 day", retention="7 days", level="INFO")
写入到文件，按大小分割（例如 500MB）
logger.add("app.log", rotation="500 MB")
写入到文件，压缩旧日志
logger.add("app.log", rotation="1 week", compression="zip")

---

4. 自定义日志格式

python

深色版本

# 自定义格式
format = "{time:YYYY-MM-DD HH:mm:ss} | {level} | {message} | {file}:{line}"
logger.add("app.log", format=format, level="INFO")

常用格式字段：

• {time}：时间
• {level}：日志级别
• {message}：日志内容
• {file}：文件名
• {function}：函数名
• {line}：行号
• {process}：进程ID
• {thread}：线程ID

---

5. 移除默认控制台输出

默认 loguru 会输出到 stderr，你可以移除它：

python

深色版本

logger.remove()  # 移除所有 handler
logger.add("app.log")  # 只输出到文件

---

6. 异常捕获（自动记录 traceback）

python

深色版本

@logger.catch
def my_function():
    1 / 0
my_function()
会自动记录异常堆栈

或者在 try-except 中手动记录：

python

深色版本

try:
    1 / 0
except Exception:
    logger.exception("发生异常")

---

7. 结构化日志（JSON 格式）

python

深色版本

import json
def json_formatter(record):

record["extra"]["json_fields"] = {

"timestamp": record["time"].timestamp(),

"level": record["level"].name,

"message": record["message"],

"file": record["file"].path,

"line": record["line"]

}

return "{extra[json_fields]}\n"
logger.add("logs.json", format=json_formatter, serialize=True)

或者使用 serialize=True 直接输出 JSON：

python

深色版本

logger.add("app.json", serialize=True)

---

8. 动态上下文信息（bind）

python

深色版本

logger = logger.bind(user="alice", action="login")
logger.info("用户登录")
# 输出：... | INFO | user='alice' action='login' | 用户登录

---

9. 日志级别控制

python

深色版本

logger.add("debug.log", level="DEBUG")
logger.add("error.log", level="ERROR")

也可以动态设置全局级别：

python

深色版本

logger.level("TRACE", no=5, color="<fg #7f7f7f>", icon="🔍")

---

10. 异步和线程安全

loguru 的 logger 是线程安全的，也支持异步日志写入（通过 enqueue=True）：

python

深色版本

logger.add("app.log", enqueue=True)  # 使用队列异步写入

---

11. 全局配置建议

通常在项目启动时配置：

python

深色版本

# setup_logger.py
from loguru import logger
import sys
logger.remove()  # 移除默认输出
控制台输出（INFO 及以上）
logger.add(

sys.stdout,

format="<green>{time:YYYY-MM-DD HH:mm:ss}</green> | "

"<level>{level: <8}</level> | "

"<cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>",

level="INFO"

)
文件输出（DEBUG 及以上，按天分割）
logger.add(

"logs/app_{time:YYYY-MM-DD}.log",

rotation="00:00",

retention="7 days",

level="DEBUG",

encoding="utf-8"

)
在其他文件中直接导入使用
from setup_logger import logger

---

总结

loguru 的优点：

• 简洁 API，无需繁琐配置
• 彩色输出，可读性强
• 支持自动分割、压缩、保留策略
• 支持结构化日志（JSON）
• 内置异常捕获装饰器
• 线程安全、异步支持

非常适合用于中小型项目或快速开发中替代原生 logging 模块。

官方文档：https://loguru.readthedocs.io/en/stable/