别再用 print 调试了!Python 官方推荐的日志实践指南

很多开发者在编写 Python 脚本时，习惯随手打上几个 print() 来查看变量状态。在写几十行代码的一波流脚本时，这确实爽快，但当项目规模从脚本演变成系统，或者当你需要在线上环境排查一个半夜出现的 Bug 时，满屏无意义的控制台输出只会让你陷入迷茫。

最近花时间又看了下 Python 官方文档，在最新的日志指南中再次强调了日志不是简单的输出。

日志的五个等级

日志分为五个等级，我觉得这非常有必要。很多同学在写代码时，通通使用 logging.info，这导致生产环境下日志量巨大，关键信息被瞬间淹没。logging.info 可以说和 print() 没有任何区别。

正确的做法是根据事件的重要程度来选择级别。

• • DEBUG 仅用于开发调试。
• • INFO 记录关键节点。
• • WARNING 则是默认的起点。
• • ERROR是当程序遇到非预期错误但仍能运行。
• • CRITICAL是代码面临无法挽救崩溃时使用。

import logging# 快速配置：将日志写入文件，只记录 INFO 及以上级别logging.basicConfig(filename='app.log', level=logging.INFO,                    format='%(asctime)s - %(levelname)s - %(message)s')def complex_logic(data):    if not data:        logging.warning("收到空数据，虽然不影响运行，但请检查来源。")        return    try:        result = 10 / data        logging.info(f"计算成功，结果为: {result}")    except ZeroDivisionError:        logging.error("除数不能为零，请修复业务逻辑。")complex_logic(0)

通过这种分级，我们可以在本地开发时开启 DEBUG 模式看清所有细节，而在生产环境仅开启 WARNING 或 ERROR，确保系统资源不被日志刷爆，同时保留了复盘问题的关键线索。

进阶使用

在大型项目中，如果你还在所有文件里直接调用 logging.info，你会发现所有的日志都挤在 root 根记录器下，根本分不清哪条消息是哪个模块发出的。

官方强烈建议使用 logging.getLogger(__name__)。这能让日志系统自动识别 Python 的模块层级。它就像给每一条日志贴上了唯一标识，让你能够针对特定的模块单独设置日志开关，而不必修改任何一行业务逻辑代码。

# module_a.pyimport logging# 获取以当前模块名为命名的 loggerlogger = logging.getLogger(__name__)def do_something():    logger.debug("这是来自 module_a 的调试信息")    logger.info("module_a 正在执行任务...")# main.pyimport loggingfrom module_a import do_somethinglogging.basicConfig(level=logging.INFO)do_something()

这种模式的优雅之处在于：如果未来你觉得某个第三方库或某个子模块的日志占用了太多位置，你可以在入口处精准地关掉它，而保持其他部分的监控依然灵敏。

日志也有坑

在处理高并发或高性能要求的代码时，日志本身也可能成为瓶颈。很多开发者习惯在日志里直接使用 Python 3.6+ 的 f-string，例如 logging.info(f"User {name} login")。虽然这很符合现代语法，但在日志语境下，这并不是官方推荐的最优解。

官方建议采用“延迟格式化”的写法。这意味着只有当日志级别满足输出条件时，Python 才会去真正拼接字符串。在高频率的循环中，这种微小的改动能节省大量不必要的内存开销。此外，对于需要长期维护的项目，统一的日志格式（Formatter）至关重要。

import logging# 推荐：延迟格式化，性能更优logging.info("用户 %s 已登录，来源 IP: %s", "knxhub.top", "192.168.1.1")# 进阶配置：同时输出到文件和控制台logger = logging.getLogger('ProApp')logger.setLevel(logging.DEBUG)# 创建处理器file_handler = logging.FileHandler('sys_complex.log')console_handler = logging.StreamHandler()# 定义统一的优雅格式formatter = logging.Formatter('%(name)s | %(levelname)-8s | %(message)s')file_handler.setFormatter(formatter)console_handler.setFormatter(formatter)# 装载处理器logger.addHandler(file_handler)logger.addHandler(console_handler)logger.info("系统多端日志初始化完成")

从 print 到 logging 的跨越，本质上是从写完就跑到长期维护思维的转变。当你的日志变得井然有序、分级明确、且自带模块信息时，排查问题将不再是靠直觉，而是如同查阅字典。