共计 5969 个字符，预计需要花费 15 分钟才能阅读完成。
前段时间帮组里排查一个线上定时任务的问题，发现日志里除了几个关键报错外，几乎没有中间过程的记录。原来开发者图省事，只用了 print 输出核心结果，导致我们定位问题时抓瞎。这让我想起自己刚入行时也犯过同样的错误。今天就来和大家聊聊，如何用 Python logging 模块告别低效的 print 调试，构建一套真正有用的日志系统。
一、初探日志：告别 print 的第一步
print 固然简单直接，但在项目越来越大、运行环境越来越复杂时，它的短板就暴露无遗了：无法区分级别、无法输出到文件、无法灵活控制输出格式。Python 内置的 logging 模块，就是解决这些痛点的瑞士军刀。
咱们先从最简单的日志记录开始。
import logging
# 配置日志系统，让它知道如何处理日志
# 我刚开始学的时候总以为 print 够用，直到线上出问题才发现日志的重要性。# 默认情况下，logging.basicConfig 会把日志输出到控制台，并且级别是 WARNING。logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
# 获取一个日志器实例
logger = logging.getLogger(__name__) # 通常我们会用当前模块名作为 logger 的名字
# 记录不同级别的日志
logger.debug("这是一条调试信息，通常用于开发阶段")
logger.info("这是一条普通信息，表示程序正常运行")
logger.warning("这是一条警告信息，可能存在潜在问题")
logger.error("这是一条错误信息，程序执行遇到问题")
logger.critical("这是一条严重错误，程序可能无法继续运行")
try:
result = 10 / 0
except ZeroDivisionError:
logger.exception("程序发生异常！") # logger.exception 会自动记录当前异常的堆栈信息，省事又好用！小提醒：
- 日志级别：
DEBUG < INFO < WARNING < ERROR < CRITICAL。basicConfig里的level参数决定了你的日志器会处理哪个级别及更高级别的消息。比如level=logging.INFO，那么debug级别的日志就不会显示了。 __name__的妙用：logging.getLogger(__name__)会根据当前模块的名称获取或创建一个 Logger 实例。好处是不同模块的日志可以独立管理，追踪起来更方便。
二、进阶配置：让日志井然有序，有家可归
光打印到控制台还不够，很多时候我们需要把日志保存到文件，或者以特定的格式输出。logging 模块通过 Handler（处理器）和 Formatter（格式器）来实现这一点。
import logging
import os
# 1. 创建一个 Logger 实例
# 生产环境中，我通常会给每个项目或核心模块定义一个独立的 Logger，便于区分和管理。logger = logging.getLogger("my_app_logger")
logger.setLevel(logging.DEBUG) # 设置总体的日志级别为 DEBUG
# 2. 创建一个文件处理器 (FileHandler)，将日志写入文件
log_file_path = "app.log"
# 以前写定时任务，日志全打到控制台，服务器重启后啥也没了，后来才知道要用 FileHandler。file_handler = logging.FileHandler(log_file_path, encoding='utf-8')
file_handler.setLevel(logging.INFO) # 文件处理器只记录 INFO 及以上级别的日志
# 3. 创建一个控制台处理器 (StreamHandler)，将日志输出到控制台
console_handler = logging.StreamHandler()
console_handler.setLevel(logging.DEBUG) # 控制台处理器记录 DEBUG 及以上级别的日志，方便开发调试
# 4. 定义一个日志格式器 (Formatter)
# 这是我比较喜欢用的格式，包含了时间、级别、Logger 名称、模块路径、行号和消息内容。# 记得用 try-except 包裹文件操作，避免文件权限或路径不存在导致程序崩溃，之前就因为这事儿踩过坑。formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(filename)s:%(lineno)d - %(message)s')
# 5. 将格式器添加到处理器
file_handler.setFormatter(formatter)
console_handler.setFormatter(formatter)
# 6. 将处理器添加到 Logger
logger.addHandler(file_handler)
logger.addHandler(console_handler)
# 7. 记录日志
logger.debug("这是一条开发阶段的调试信息。") # 会出现在控制台，但不会写入文件
logger.info("用户成功登录。用户 ID: 12345") # 会同时出现在控制台和文件中
logger.warning("配置文件丢失，使用默认设置。") # 会同时出现在控制台和文件中
# 模拟一个异常
try:
result = 1 / 0
except ZeroDivisionError:
logger.error("计算失败，发生除零错误！", exc_info=True) # exc_info=True 会把异常信息包含在日志中
# 之前遇到过线上错误，只记录了错误信息但没堆栈，定位问题花了两天，后来都习惯加 exc_info=True 了。# 确保文件关闭
# os.remove(log_file_path) # 测试结束后可以删除日志文件 小提醒：
- Handler 的多样性： 除了
FileHandler和StreamHandler，logging还有RotatingFileHandler（按大小或时间自动轮转日志文件，避免单个文件过大）、TimedRotatingFileHandler等，这些在生产环境中非常重要，能有效管理日志存储。 exc_info=True： 这是记录异常时一个非常实用的参数，它会自动将当前的异常信息（包括堆栈跟踪）添加到日志消息中，对于调试线上问题至关重要。- Logger 的层次结构：
getLogger("my_app_logger")是一个具体的 Logger。如果你再getLogger("my_app_logger.sub_module")，这个子 Logger 会继承父 Logger 的配置，实现日志的层级管理。
三、团队协作与模块化：构建统一的日志系统
在一个大型项目中，每个模块都自己搞一套 basicConfig 或者 getLogger，会导致日志行为混乱。最佳实践是构建一个统一的日志配置入口。
我们可以在项目根目录创建一个 log_config.py 文件，或者直接在主入口文件里完成配置。
# log_config.py (或者放在你的 __init__.py 或者主入口文件里)
import logging
import logging.handlers # 导入 handlers 模块
import os
def setup_logging(log_file_name="application.log", log_dir="logs", level=logging.INFO):
"""配置项目的日志系统。"""
# 确保日志目录存在
if not os.path.exists(log_dir):
os.makedirs(log_dir)
# 这里加 os.makedirs 是因为之前有同事不注意目录创建，导致日志文件写不进去报错。log_file_path = os.path.join(log_dir, log_file_name)
# 获取根 Logger
root_logger = logging.getLogger()
root_logger.setLevel(level) # 设置根 Logger 的最低处理级别
# 避免重复添加 Handler
# 我带过的实习生，每个文件都 basicConfig 一遍，结果日志行为混乱，后来才教他们这么统一管理。# 每次调用 setup_logging 时，先清空可能已存在的 Handler，防止日志重复输出。if not root_logger.handlers:
# 文件处理器 (按大小轮转，最大 10MB，保留 5 个备份文件)
file_handler = logging.handlers.RotatingFileHandler(
log_file_path,
maxBytes=10 * 1024 * 1024, # 10 MB
backupCount=5,
encoding='utf-8'
)
file_handler.setLevel(logging.DEBUG) # 文件中记录所有 DEBUG 及以上信息
# 控制台处理器
console_handler = logging.StreamHandler()
console_handler.setLevel(logging.INFO) # 控制台只输出 INFO 及以上信息
# 格式器
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(module)s.%(funcName)s:%(lineno)d - %(message)s'
)
file_handler.setFormatter(formatter)
console_handler.setFormatter(formatter)
root_logger.addHandler(file_handler)
root_logger.addHandler(console_handler)
# ----------------- 使用示例 -----------------
# 假设这是你的主应用入口
if __name__ == "__main__":
setup_logging(level=logging.DEBUG) # 在应用启动时调用一次
# 获取当前模块的 Logger
main_logger = logging.getLogger(__name__)
main_logger.info("应用程序启动成功。")
main_logger.debug("这是主模块的调试信息，只有当根 Logger 设置为 DEBUG 时才显示。")
# 模拟另一个模块
def some_function_in_another_module():
func_logger = logging.getLogger("another_module") # 获取另一个模块的 Logger
func_logger.warning("另一个模块发现了一个潜在问题。")
try:
result = 1 / 0
except ZeroDivisionError:
func_logger.error("另一个模块发生了错误！", exc_info=True)
some_function_in_another_module()
main_logger.info("应用程序运行结束。")小提醒：
logging.getLogger()的单例模式： 无论你在哪里调用logging.getLogger("my_logger")多少次，它总是返回同一个Logger实例。这对于避免重复创建 Handler 从而导致日志重复输出，或文件句柄泄露至关重要。我亲测有效，避免了不少坑。- 根 Logger：
logging.getLogger()（不带参数）返回的是根 Logger。它是所有其他 Logger 的父级，所以对其进行配置可以影响到整个应用程序的日志行为。 RotatingFileHandler： 在生产环境中，这是日志文件管理的关键。它会根据设定的条件（文件大小或时间）自动创建新的日志文件，并删除旧的备份文件，避免日志文件无限膨胀占满磁盘。
四、常见误区与避坑指南
作为一名资深开发者，我见过和踩过太多日志相关的坑，给大家总结几个常见的：
-
误区一：混淆 Logger 级别和 Handler 级别
- 现象： 明明设置了
logger.setLevel(logging.DEBUG)，却还是看不到DEBUG级别的日志。 - 原因：
Logger的级别是过滤器，它决定了哪些消息会被 Logger 接收。而Handler也有自己的级别，它决定了从 Logger 接收到的消息中，哪些会被 Handler 处理并输出。只有当消息级别高于或等于 Logger 和所有相关 Handler 的级别时，这条日志才会被最终处理。 - 避坑： 确保你的 Logger 级别和至少一个 Handler 的级别都设置到你期望的最低级别。我刚开始总是觉得为啥设置了
DEBUG还是看不到，原来Handler的级别没设对，花了半天时间才找到问题。
- 现象： 明明设置了
-
误区二：在循环或频繁调用的函数中重复创建 Handler
- 现象： 程序运行一段时间后，日志输出变得混乱，或者出现文件句柄耗尽、内存飙升等问题。
- 原因： 每次创建
FileHandler都会打开一个文件句柄。如果在循环中重复创建，会导致大量文件句柄未关闭，最终耗尽系统资源。 - 避坑：
Handler应该在应用启动时一次性创建，然后添加到 Logger 中。利用logging.getLogger()的单例特性，确保不会重复添加Handler（通过检查logger.handlers是否为空来判断）。有次写爬虫，每个请求都新建FileHandler，内存和文件句柄爆了，学费交得有点贵。
-
误区三：不管理日志文件，导致磁盘空间耗尽
- 现象： 应用程序运行一段时间后，日志文件变得巨大，甚至占满服务器磁盘空间，导致系统崩溃。
- 原因： 默认的
FileHandler会一直向同一个文件写入日志，不会自动进行管理。 - 避坑： 生产环境务必使用
logging.handlers.RotatingFileHandler或logging.handlers.TimedRotatingFileHandler。它们可以根据文件大小或时间自动轮转日志文件，并删除旧的备份，有效管理日志文件的生命周期。
总结
日志是软件的眼睛，良好日志实践是构建稳定、可维护系统的基石。通过合理配置 logging 模块，咱们不仅能告别低效的 print 调试，还能为应用程序提供强大的可观测性。从今天起，让你的 Python 项目拥有高质量的日志吧！
你在用 Python logging 时遇到过哪些有趣的“坑”或独家技巧呢？欢迎在评论区分享！
正文完
