Python 日志 logging 入门：别再用 print 调试了

很多新手写 Python 时，调试全靠 print：哪里不对就插一句 print，跑完再删掉。程序一小没问题，程序一大、跑在服务器上没人盯着时，print 就不够用了：信息混在一起分不清轻重，想找某次运行的记录也找不到。这时该用标准库 logging，它不用装第三方包，几行就能搭起一套像样的日志。

先分清级别

logging 有五个常用级别，从轻到重依次是 DEBUG、INFO、WARNING、ERROR、CRITICAL。写日志时先想清楚这条信息属于哪一级：调试细节用 DEBUG，正常流程的关键节点用 INFO，可能有问题但还能继续用 WARNING，出错用 ERROR，程序快撑不住了用 CRITICAL。级别分好后，排查时按级别过滤，一眼就能定位。

默认配置只显示 WARNING 及以上，所以新手常遇到“明明写了 logging.info，怎么没输出”。这不是代码错了，而是默认门槛拦住了。起手这样配就够用：

import logging

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s %(levelname)s %(name)s: %(message)s",
    datefmt="%Y-%m-%d %H:%M:%S",
)
logger = logging.getLogger(__name__)

logger.info("服务启动，开始处理任务")
logger.warning("重试第 2 次，接口返回 502")

format 里的字段值得记一下：asctime 是时间，levelname 是级别，name 是模块名，message 是正文。带上时间和模块名，事后翻日志才能还原现场；只打印一句话的日志，出了问题等于没记。

输出到文件，别只打屏幕

跑在服务器上的程序，屏幕输出关掉窗口就没了。加一个 FileHandler，把日志同时写进文件：

handler = logging.FileHandler("app.log", encoding="utf-8")
handler.setFormatter(logging.Formatter(
    "%(asctime)s %(levelname)s %(name)s: %(message)s"))
logger.addHandler(handler)

文件日志有个好习惯：按天或按大小轮换，别让单个日志文件无限长下去。标准库的 RotatingFileHandler 可以按大小切分，TimedRotatingFileHandler 可以按天切分，程序跑几个月也不怕磁盘被日志塞满。

三个容易踩的坑

第一，不要在日志里打印密码、Token、完整请求体里的敏感字段。日志文件常会被打包发给别人排查，敏感信息一旦写进去就很难收回。

第二，不要用 f-string 拼日志正文再传给 logger。推荐写成 logger.info("处理用户 %s，耗时 %.2f 秒", user_id, cost) 这种 lazy 写法：级别被过滤掉时，字符串根本不会拼接，性能更好。

第三，不要每个模块都 basicConfig 一次。basicConfig 只在第一次调用时生效，后面再调基本不起作用。正确做法是在程序入口配置一次，各模块只 getLogger(__name__) 取用。

从 print 迁移的小步骤

已有代码里 print 很多，不用一次全改。先把关键路径的 print 换成 logger.info，把异常处的 print 换成 logger.exception——它会自动带上完整的异常堆栈，比 print(e) 只看一行错误信息有用得多。跑一周下来，你会发现排查问题从“重新加 print 再复现”变成了“直接翻日志找时间点”，这就是 logging 值回票价的地方。

工具本身不复杂，难的是养成习惯：每写一个可能出错、可能要事后复盘的地方，顺手记一条分好级别的日志。程序越跑越久，这份习惯的回报就越大。