python环境搭建 (九) 极简日志工具 loguru

Python极简日志工具：loguru==0.7.3 功能与完整使用指南

在Python开发中，原生logging模块虽功能完整，但存在配置繁琐、异常捕获不友好、日志文件管理复杂 等问题，而loguru==0.7.3是一款专为简化日志开发设计的第三方库，以零配置开箱即用、异常堆栈自动捕获、日志文件智能管理、语法极简 为核心优势，完美替代原生logging，成为Python生态中最流行的日志工具之一。0.7.3是其稳定版本，兼容Python3.7+，无重大兼容性问题，可直接用于个人开发、团队项目甚至生产环境。

本文将从核心功能、安装、基础使用、进阶配置、生产环境实用示例 等方面，全面讲解loguru==0.7.3的使用方法，所有示例开箱即用，适配指定版本。

一、loguru==0.7.3 核心功能（对比原生logging的核心优势）

loguru的核心设计理念是「让日志记录变得简单 」，无需手动创建logger实例、配置处理器/格式化器/过滤器，导入即可使用，同时解决了原生logging的诸多痛点，核心功能如下：

1. 零配置开箱即用

无需任何配置代码，导入logger后直接调用debug/info/error等方法，默认输出彩色日志到控制台，格式包含时间、级别、模块、行号、日志信息，开箱即用。

2. 强大的异常捕获与堆栈打印

专门提供logger.exception()方法，在异常捕获块中使用，可自动打印完整的异常堆栈信息 ，并包含变量上下文，无需手动调用traceback，调试效率提升数倍。

3. 日志文件智能管理

一行代码即可将日志输出到文件，支持自动按大小/时间分割日志、日志文件自动保留/清理、压缩旧日志，无需手动编写文件轮转逻辑，完美适配生产环境。

4. 支持多格式与自定义配置

内置彩色输出、JSON格式日志，支持自定义日志格式（时间格式、字段展示、颜色配置），满足控制台调试、文件存储、日志收集等不同场景需求。

5. 线程/进程/协程安全

日志记录天生支持多线程、多进程、异步协程（asyncio） ，无需额外加锁，避免多场景下日志混乱、丢失的问题，原生logging需手动配置线程安全。

6. 极简的API设计

仅通过核心的logger实例和add/remove方法即可实现所有功能，无需记忆复杂的类和方法，学习成本极低，新手也能快速上手。

7. 灵活的日志级别控制

支持Python标准日志级别（DEBUG<INFO<WARNING<ERROR<CRITICAL），可通过配置过滤指定级别日志，也可动态添加/移除日志输出目标（控制台/文件/网络）。

二、快速安装（指定0.7.3版本）

loguru的安装极其简单，打开终端/命令行，执行pip命令即可，推荐使用国内源加速，避免下载慢/失败，Python3建议用pip3：

# 基础安装指定版本
pip install loguru==0.7.3
# 国内清华源加速（推荐）
pip install loguru==0.7.3 -i https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后，在Python代码中直接导入即可使用，无需额外验证，无依赖冲突问题。

三、基础使用：零配置快速上手

loguru的核心是logger实例，无需手动创建 ，直接从loguru导入即可，默认配置已满足日常开发的控制台日志需求，这也是其与原生logging最核心的区别。

3.1 核心步骤：导入+直接调用日志级别方法

新建test_loguru.py，写入以下代码，直接运行即可看到效果：

# 无需配置，直接导入logger
from loguru import logger

# 5个标准日志级别，从低到高：DEBUG < INFO < WARNING < ERROR < CRITICAL
logger.debug("这是DEBUG级别日志：调试信息，开发阶段排查问题使用")
logger.info("这是INFO级别日志：常规运行信息，记录业务流程")
logger.warning("这是WARNING级别日志：警告信息，非错误但需注意（如配置缺失）")
logger.error("这是ERROR级别日志：错误信息，业务逻辑执行失败（如接口调用失败）")
logger.critical("这是CRITICAL级别日志：严重错误，系统无法正常运行（如数据库连接失败）")

3.2 默认输出效果（控制台）

运行代码后，控制台会输出彩色日志（不同级别不同颜色，如DEBUG蓝色、INFO白色、WARNING黄色、ERROR红色、CRITICAL亮红色），默认格式为：

2026-02-04 15:30:00.123 | DEBUG    | __main__:<module>:6 - 这是DEBUG级别日志：调试信息，开发阶段排查问题使用
2026-02-04 15:30:00.124 | INFO     | __main__:<module>:7 - 这是INFO级别日志：常规运行信息，记录业务流程
2026-02-04 15:30:00.124 | WARNING  | __main__:<module>:8 - 这是WARNING级别日志：警告信息，非错误但需注意（如配置缺失）
2026-02-04 15:30:00.124 | ERROR    | __main__:<module>:9 - 这是ERROR级别日志：错误信息，业务逻辑执行失败（如接口调用失败）
2026-02-04 15:30:00.125 | CRITICAL | __main__:<module>:10 - 这是CRITICAL级别日志：严重错误，系统无法正常运行（如数据库连接失败）

默认格式包含时间（精确到毫秒）、日志级别、模块名、行号、日志信息 ，精准定位日志产生位置，比原生logging的默认格式更实用。

四、核心进阶使用：满足90%的开发场景

基础控制台日志仅适用于本地调试，实际开发中还需要输出日志到文件、捕获异常堆栈、自定义日志格式、管理日志文件 等功能，loguru通过核心的logger.add()方法实现所有扩展配置，该方法是loguru的核心，用于添加日志输出目标（处理器），支持文件、控制台、网络等多种目标，且支持多目标同时输出。

4.1 输出日志到文件（最常用）

一行代码即可将日志同时输出到控制台+文件 ，logger.add()接收文件路径作为参数，自动创建文件（父目录不存在则报错，需提前创建），示例：

from loguru import logger

# 添加文件日志处理器，日志同时输出到控制台和test.log文件
logger.add("test.log")

# 后续日志会同时在控制台显示、写入文件
logger.info("日志同时输出到控制台和文件")
logger.error("错误信息也会被写入文件")

执行后，项目目录会生成test.log文件，内容为纯文本格式（无颜色），包含与控制台一致的日志信息，实现「控制台调试、文件留存」的双重需求。

4.2 日志文件智能轮转（生产环境必备）

生产环境中，单个日志文件会持续增大，导致难以打开和管理，loguru支持按文件大小、时间自动分割日志 ，并可配置日志保留数量、自动压缩旧日志 ，所有配置均通过logger.add()的参数实现，无需额外代码：

from loguru import logger
import time

# 配置日志文件轮转：按大小+时间分割，自动保留+压缩
# 核心参数说明：
# rotation：轮转规则，"500MB"=按大小，"1d"=按天，"1h"=按小时，"10:00"=每天10点
# retention：保留规则，"7d"=保留7天，10=保留10个文件
# compression：压缩格式，"zip"=压缩为zip包，节省磁盘空间
logger.add(
    "app_{time}.log",  # {time}自动添加时间戳，区分不同轮转文件
    rotation="500MB",  # 单个文件最大500MB，超过则自动新建
    retention="7d",    # 仅保留最近7天的日志文件
    compression="zip", # 旧日志自动压缩为zip
    encoding="utf-8"   # 编码为utf-8，避免中文乱码
)

# 模拟日志输出
for i in range(10):
    logger.info(f"生产环境日志示例 - {i}")
    time.sleep(0.1)

执行后，会生成以app_时间戳.log命名的文件，当文件达到500MB或超过7天时，会自动触发轮转：新建日志文件、删除过期文件、将旧文件压缩为zip包，完美解决生产环境日志管理问题。

4.3 自动捕获异常堆栈（调试神器）

这是loguru最实用的功能之一，在try-except异常捕获块中，使用logger.exception()替代普通级别方法，可自动打印完整的异常堆栈信息 ，包括异常类型、出错行号、调用栈，甚至变量上下文，无需手动导入traceback，示例：

from loguru import logger

def divide(a, b):
    return a / b

if __name__ == "__main__":
    try:
        divide(10, 0)  # 触发除零异常
    except Exception as e:
        # 关键：使用logger.exception()，自动打印完整堆栈
        logger.exception("执行除法运算时发生错误：")
        # 普通logger.error()仅打印异常信息，无堆栈
        # logger.error(f"执行除法运算时发生错误：{e}")

执行后，控制台会输出详细的异常堆栈，包含出错函数、行号、调用链、异常类型，示例输出片段：

2026-02-04 16:00:00.123 | ERROR    | __main__:<module>:12 - 执行除法运算时发生错误：
Traceback (most recent call last):
  File "test_loguru.py", line 10, in <module>
    divide(10, 0)
  File "test_loguru.py", line 6, in divide
    return a / b
ZeroDivisionError: division by zero

相比原生logging需要手动拼接traceback.format_exc()，loguru的exception()方法实现了「一行捕获所有异常信息」，大幅提升调试效率。

4.4 自定义日志格式

loguru支持通过format参数自定义日志格式，使用占位符表示日志字段，满足个性化的展示需求（如调整时间格式、添加进程ID/线程ID、隐藏模块名等），常用占位符如下：

占位符	含义
{time}	日志产生时间（可自定义格式）
{level}	日志级别（DEBUG/INFO等）
{process}	进程ID
{thread}	线程ID
{module}	模块名
{line}	行号
{message}	日志内容

自定义格式示例（添加进程/线程ID，简化时间格式，仅保留核心字段）：

from loguru import logger

# 自定义日志格式，同时输出到控制台和custom_format.log
logger.add(
    "custom_format.log",
    format="{time:YYYY-MM-DD HH:mm:ss} | {level:8} | 进程:{process} | 线程:{thread} | {module}:{line} | {message}",
    level="INFO",  # 过滤级别：仅输出INFO及以上日志
    encoding="utf-8"
)

logger.debug("该日志会被过滤（级别低于INFO）")
logger.info("自定义格式的INFO日志，包含进程和线程ID")
logger.error("自定义格式的ERROR日志，方便生产环境排查问题")

执行后，文件中的日志格式为自定义样式，且DEBUG级别日志被过滤，仅保留INFO及以上，示例输出：

2026-02-04 16:10:00 | INFO     | 进程:1234 | 线程:5678 | test_loguru:15 | 自定义格式的INFO日志，包含进程和线程ID
2026-02-04 16:10:00 | ERROR    | 进程:1234 | 线程:5678 | test_loguru:16 | 自定义格式的ERROR日志，方便生产环境排查问题

4.5 动态添加/移除日志处理器

logger.add()方法会返回一个唯一的处理器ID（整数） ，通过logger.remove(处理器ID)可动态移除指定的日志输出目标，避免日志重复输出，也可通过logger.remove()（无参数）移除所有非默认处理器（默认控制台处理器无法被移除），示例：

from loguru import logger

# 添加文件处理器，获取处理器ID
file_handler_id = logger.add("temp.log")
logger.info("该日志会写入temp.log并输出到控制台")

# 移除指定的文件处理器
logger.remove(file_handler_id)
logger.info("该日志仅输出到控制台，不再写入temp.log")

# 重新添加新的处理器
new_handler_id = logger.add("new_temp.log")
logger.info("该日志写入new_temp.log并输出到控制台")

# 移除所有非默认处理器（删除new_temp.log的处理器）
logger.remove()
logger.info("该日志仅输出到控制台")

4.6 输出JSON格式日志（适配日志收集系统）

生产环境中，日志通常会被ELK、Loki等日志收集系统解析，而JSON格式 是最易被解析的格式，loguru通过serialize=True参数可一键输出JSON格式日志，无需手动序列化，示例：

from loguru import logger

# 输出JSON格式日志到json_logs.log，适配日志收集系统
logger.add(
    "json_logs.log",
    serialize=True,  # 核心：开启JSON序列化
    encoding="utf-8"
)

logger.info("JSON格式日志，包含所有日志字段")
logger.error("JSON格式错误日志，方便日志系统检索分析")

执行后，json_logs.log中的每条日志都是一个独立的JSON对象，包含time、level、message、module、line等所有字段，示例：

{"time": "2026-02-04T16:20:00.123456+08:00", "level": "INFO", "message": "JSON格式日志，包含所有日志字段", "module": "test_loguru", "line": 8, ...}
{"time": "2026-02-04T16:20:00.124567+08:00", "level": "ERROR", "message": "JSON格式错误日志，方便日志系统检索分析", "module": "test_loguru", "line": 9, ...}

五、生产环境实用综合配置示例

结合以上所有核心功能，提供一套可直接用于生产环境的loguru配置，实现「控制台彩色日志+文件轮转日志+JSON格式日志+异常捕获+日志过滤」的全功能需求，兼顾本地调试和生产环境日志管理：

from loguru import logger
import os

# 确保日志目录存在，避免新建文件时报错
LOG_DIR = "logs"
if not os.path.exists(LOG_DIR):
    os.makedirs(LOG_DIR)

# 1. 移除所有非默认处理器（避免重复输出）
logger.remove()

# 2. 添加控制台处理器：彩色输出，仅显示INFO及以上（本地调试可改为DEBUG）
logger.add(
    sink=lambda msg: print(msg, end=""),  # 输出到控制台
    format="{time:YYYY-MM-DD HH:mm:ss} | {level:8} | {module}:{line} | {message}",
    level="INFO",
    colorize=True  # 开启彩色输出
)

# 3. 添加普通文本日志处理器：按大小+时间轮转，保留30天，自动压缩（用于人工排查）
logger.add(
    sink=os.path.join(LOG_DIR, "app_{time:YYYYMMDD}.log"),
    format="{time:YYYY-MM-DD HH:mm:ss.SSS} | {level:8} | 进程:{process} | 线程:{thread} | {module}:{line} | {message}",
    level="DEBUG",  # 文件日志保留所有级别，方便详细排查
    rotation="1GB",  # 单个文件1GB，超过轮转
    retention="30d", # 保留30天日志
    compression="zip",# 旧日志压缩
    encoding="utf-8",
    enqueue=True  # 开启异步入队，提升性能，避免日志阻塞业务
)

# 4. 添加JSON格式日志处理器：按天轮转，保留7天（适配日志收集系统）
logger.add(
    sink=os.path.join(LOG_DIR, "app_json_{time:YYYYMMDD}.log"),
    level="INFO",
    rotation="1d",  # 按天轮转
    retention="7d",
    serialize=True,  # JSON格式
    encoding="utf-8",
    enqueue=True
)

# 测试日志输出
if __name__ == "__main__":
    logger.debug("调试日志：仅写入文本文件，不输出到控制台")
    logger.info("系统启动成功，开始处理业务")
    logger.warning("配置文件未找到，使用默认配置")
    try:
        1 / 0
    except Exception:
        logger.exception("发生除零异常，业务处理中断")
    logger.critical("数据库连接失败，系统即将退出")

配置说明：

1. 日志按功能拆分：控制台用于实时查看，文本文件用于人工详细排查，JSON文件用于日志系统解析；
2. 开启enqueue=True：异步写入日志，避免日志IO操作阻塞业务代码，提升生产环境性能；
3. 按级别过滤：控制台仅显示INFO及以上，减少冗余输出，文件日志保留DEBUG级别，方便排查问题；
4. 日志目录自动创建：避免因目录不存在导致的报错，适配不同部署环境。

六、与Python原生logging的核心对比

为了更清晰地体现loguru的优势，以下是loguru==0.7.3与Python原生logging的核心对比，直观看到为什么loguru更适合现代Python开发：

特性	loguru==0.7.3	Python原生logging
配置复杂度	零配置，导入即用	需手动创建logger、处理器、格式化器，配置繁琐
异常捕获	logger.exception()一键打印完整堆栈	需手动导入traceback，拼接堆栈信息
日志文件管理	一行配置自动轮转、保留、压缩	需手动配置RotatingFileHandler/TimedRotatingFileHandler，功能简陋
彩色输出	内置支持，一键开启	需第三方库（如colorlog），额外配置
JSON格式	serialize=True一键实现	需自定义格式化器，手动序列化
线程/进程安全	天生支持，无需额外配置	需手动加锁，否则日志混乱
异步日志	enqueue=True一键开启	需自定义异步处理器，开发成本高
API设计	极简，仅logger+add/remove	复杂，包含Logger/Handler/Formatter/Filter等多个类
中文乱码	可直接指定encoding=utf-8	需手动配置处理器编码，易踩坑

七、loguru==0.7.3 关键注意点（避坑指南）

1. Python版本要求 ：0.7.3仅支持Python3.7+，若项目需兼容Python3.6及以下，需使用loguru0.6.x版本；
2. 中文乱码问题 ：添加文件处理器时，务必指定encoding="utf-8"，否则Windows环境下日志文件会出现中文乱码；
3. logger.exception()使用场景 ：该方法仅能在try-except异常捕获块中使用，在非异常块中使用会打印空的堆栈信息；
4. 日志路径问题 ：推荐使用绝对路径配置日志文件，避免项目运行目录变化导致日志文件创建失败；
5. enqueue=True的使用：生产环境建议开启，提升日志写入性能，避免阻塞业务，但本地调试可关闭，保证日志实时输出；
6. 处理器移除 ：多次调用logger.add()会添加多个处理器，导致日志重复输出，建议在添加自定义处理器前，先执行logger.remove()移除所有非默认处理器；
7. 日志级别过滤 ：level参数表示「仅输出该级别及以上的日志」，如level="INFO"会过滤DEBUG级别日志，文件日志建议保留DEBUG级别，方便排查。

八、总结

loguru==0.7.3是一款极简、强大、实用 的Python日志工具，以零配置开箱即用为核心，解决了原生logging的所有痛点，其核心优势可概括为：配置简单、使用便捷、功能完善、性能优异。

1. 核心定位 ：替代Python原生logging，适用于所有Python项目（个人开发、团队协作、生产环境）；
2. 核心用法 ：导入logger直接调用级别方法（debug/info/error等），通过logger.add()配置日志输出目标（控制台/文件/JSON）；
3. 核心亮点：一键异常堆栈捕获、日志文件智能轮转、JSON格式支持、线程/进程/协程安全、异步日志写入；
4. 生产环境关键配置 ：控制台+文本文件+JSON文件多目标输出、开启自动轮转/保留/压缩、指定utf-8编码、开启enqueue=True提升性能；
5. 学习成本：API设计极简，无需记忆复杂的类和方法，新手半小时即可上手，大幅提升开发和调试效率。

无论是简单的脚本开发，还是复杂的Web项目（Django/Flask/FastAPI）、异步项目，loguru==0.7.3都能完美适配，是Python开发者的必备日志工具。