如果项目里还在用 print 输出异常，或者用标准 logging 时每次都要手动拼 exc_info=True，排查线上问题时通常会错过关键现场。Loguru 把异常处理做得更直接，logger.exception 会捕获当前异常上下文，把堆栈、局部变量和线程信息一起写入日志文件，不需要额外配置。本文从文件输出、代码捕获、全局兜底和上下文增强几个角度，说明如何让 Loguru 稳定记录 Python 异常。
一、Loguru 文件输出与基础配置
Loguru 的核心入口是 from loguru import logger，这个 logger 是全局单例，不需要像标准 logging 那样先创建 Logger 再添加 Handler。默认情况下 logger 会把日志打印到 stderr，要把日志写入文件，需要调用 logger.add。logger.add 的参数非常灵活，rotation 按大小或时间轮转，retention 控制保留时长，compression 自动压缩旧日志，level 设置最低输出级别。下面是一个常见的文件配置。
from loguru import logger
logger.add(
"app.log",
rotation="1 MB",
retention="10 days",
compression="zip",
level="DEBUG"
)
def divide(a, b):
return a / b
if __name__ == "__main__":
try:
result = divide(10, 0)
except ZeroDivisionError:
logger.exception("计算除法时发生异常")
rotation="1 MB" 表示文件达到 1MB 后自动轮转；retention="10 days" 表示只保留最近 10 天的日志；compression="zip" 会把历史日志压缩，避免占用过多磁盘。需要注意的是，如果手动拼接 Windows 路径，要保留反斜杠，例如 C:\logs\app.log，不要写成 C:/logs/app.log。这种写法在跨平台项目里尤其容易出错，但 Loguru 本身会接受普通字符串路径，不需要手动转义反斜杠。
logger.add 可以多次调用，同时输出到控制台和文件。比如 logger.add(sys.stderr, level="DEBUG")，再 logger.add("app.log", level="ERROR")。这样可以让控制台保持简洁，同时保证错误级别日志一定落盘。使用 logger.exception 时，除了传入消息字符串外，Loguru 默认会开启 diagnose 参数，记录局部变量的值，这在调试复杂异常时非常有用。
二、在代码中捕获异常并写入日志
常规写法是在 try except 块中调用 logger.exception。与标准 logging 的 logging.exception 类似，但 Loguru 不需要在 logger.error 里传入 exc_info=True，logger.exception 已经等同于 logger.error 加自动异常信息提取。它会直接使用 sys.exc_info() 的结果，减少重复样板代码。
from loguru import logger
logger.add("app.log", rotation="1 MB", retention="10 days", level="DEBUG")
def read_config(path):
with open(path, "r", encoding="utf-8") as f:
return f.read()
if __name__ == "__main__":
try:
config = read_config("/tmp/not_exist.json")
except FileNotFoundError:
logger.exception("读取配置文件失败")
当 FileNotFoundError 被捕获后，logger.exception 会把异常类型、消息和完整堆栈写入 app.log。日志内容不仅包括抛出位置，还包括 read_config 函数每一层调用的参数和局部变量。这样无需再手动调用 traceback.format_exc。如果某些信息比较敏感，可以通过 logger.add 的 backtrace=False 或 diagnose=False 关闭局部变量采集，只保留堆栈，减少日志文件体积。
实际项目里，建议在 except 块中传入更具业务含义的消息，而不是只写“出错了”。例如记录用户 ID、请求参数或任务 ID，方便后续检索。Loguru 允许直接使用 f-string 或 format 风格，但更推荐使用 logger.bind 绑定上下文字段，这部分会在后面展开。
三、全局异常捕获与崩溃兜底
try except 只能覆盖你预先知道的位置，对于没有捕获的异常，程序会直接退出，可能完全来不及记录。Loguru 提供了 logger.catch 装饰器，也可以配合 sys.excepthook 做全局兜底。logger.catch 可以装饰函数，当函数内抛出任意异常时，日志会自动记录，并且默认情况下函数返回 None，不会继续向外抛出，这适合一些后台任务或回调函数。
from loguru import logger
logger.add("task.log", level="ERROR", backtrace=True, diagnose=True)
@logger.catch
def process_order(order_id):
if order_id == 0:
raise ValueError("无效订单")
return order_id * 2
result = process_order(0)
print(result)
process_order(0) 会触发 ValueError，由于被 logger.catch 包裹，异常不会中断整个脚本，result 会变成 None。如果希望异常继续向上传递，可以给 logger.catch 传入 reraise=True；如果希望捕获后执行特定清理逻辑，也可以使用 with logger.catch(): 上下文管理器，而不是装饰器。
对于全局未捕获异常，可以使用 sys.excepthook 替换。Loguru 的 logger.opt(exception=...) 可以接收三元组形式的异常信息，这样即使不在 except 块内也能记录完整堆栈。
import sys
from loguru import logger
logger.add("crash.log", level="ERROR", backtrace=True, diagnose=True)
def global_exception_handler(exc_type, exc_value, exc_traceback):
if issubclass(exc_type, KeyboardInterrupt):
sys.__excepthook__(exc_type, exc_value, exc_traceback)
return
logger.opt(exception=(exc_type, exc_value, exc_traceback)).error("未捕获异常导致程序退出")
sys.excepthook = global_exception_handler
raise RuntimeError("测试全局异常")
这里通过 sys.excepthook 捕获主线程未处理异常，logger.opt(exception=...) 会把三元组转成可读堆栈。KeyboardInterrupt 仍然交给系统默认处理，避免影响 Ctrl+C 退出。需要注意的是，sys.excepthook 在多线程程序中不会捕获子线程异常，子线程需要在线程函数内部使用 logger.catch 或 try except 自行处理。
四、异常日志的上下文增强与排查技巧
光记录异常类型和堆栈有时还不够，比如同一个接口报错，不同用户触发的场景可能完全不同。Loguru 支持通过 logger.bind 绑定自定义字段，这些字段会自动出现在每一条日志中，不需要每次手动拼接。配合自定义 format，可以让日志文件直接输出用户 ID、请求 ID 或业务模块，排查时能快速过滤出相关记录。
from loguru import logger
logger.add(
"context.log",
format="{time:YYYY-MM-DD HH:mm:ss} | {level} | {extra[user_id]} | {message}",
level="DEBUG"
)
user_logger = logger.bind(user_id="u_10086")
try:
raise PermissionError("无权访问该资源")
except PermissionError:
user_logger.exception("权限校验失败")
format 里使用 {extra[user_id]} 可以取出绑定的自定义字段。logger.bind 返回一个新的 logger 实例，原来的全局 logger 不受影响。这种绑定可以在请求开始时创建，比如 user_logger = logger.bind(request_id=request_id)，随后该请求的所有异常日志都会带上 request_id。
在异常频繁的业务中，建议结合日志级别区分。logger.debug 记录正常分支，logger.warning 记录可恢复问题，logger.exception 或 logger.error 记录需要立即处理的错误。不要把所有信息都打成 ERROR，否则告警系统会被噪声淹没。Loguru 的 level 参数可以自定义级别，也可以按模块过滤，比如 logger.add("business.log", filter=lambda record: "biz" in record["extra"])。
Loguru 的记录异常能力主要来自 logger.exception、logger.catch 和 sys.excepthook 组合。小型脚本可以直接用 logger.exception 写入文件；后台任务用 logger.catch 保证异常可见；服务型应用则建议在入口统一配置 sys.excepthook，并为关键业务绑定 request_id 等上下文。这样发生问题时，日志文件不再只是简单的一堆堆栈，而是可以快速定位到具体请求和参数的可检索记录。