Python logging 为什么同一条日志打印两遍

平时写Python脚本或者后端服务的时候，不少人都遇到过调用logging模块输出日志，同一条内容却在控制台打两次的情况，这个问题不是你代码里重复写了日志输出方法，基本都是logging本身的层级传播特性导致的。

日志重复打印的核心原因是当前使用的logger对象已经配置了输出处理器，同时它的上层父节点logger也挂载了输出处理器，日志记录会沿着logging的层级链向上传递，被多个不同的Handler先后捕获输出，最终产生同一条日志输出两遍的现象。

Python logging 同一条日志打印两遍，最常见的原因是同一条 LogRecord 被两个 Handler 消费了：子 logger 自己挂了 handler，同时因为 propagate=True 又把记录交给了 root logger。先查 handler 数量和传播链，再决定只保留 root 输出，或让子 logger 独立输出并关闭传播。

先看清重复输出的调用链

logger 负责产生和传递记录，handler 才负责把记录写到控制台、文件等目的地。名称带点号时会形成层级，例如 service.api 是 service 的后代；记录到达子 logger 后，如果传播开着，就会继续交给祖先 logger 的 handler。

因此，下面这种组合会出现两行相同消息：service.api 有一个 StreamHandler，root 也有一个 StreamHandler，而子 logger 的 propagate 仍为 True。两个 handler 的格式可以不同，但它们处理的是同一个记录。

用四个属性定位到底是谁重复了

先不要修改业务日志调用，在初始化完成后检查四件事：当前 logger 的 handlers、root 的 handlers、当前 logger 的 propagate，以及配置函数是否被重复执行。

import logging

logger = logging.getLogger("service.api")
root = logging.getLogger()

# 只打印配置状态，不改变现有 logger 配置
print("logger:", logger.name, "propagate=", logger.propagate)
print("logger handlers:", [type(h).__name__ for h in logger.handlers])
print("root handlers:", [type(h).__name__ for h in root.handlers])
print("parent:", logger.parent.name if logger.parent else None)

如果当前 logger 和 root 都有 handler，优先检查它们是否指向同一输出目的地。若每次热重载、请求初始化或函数调用都会执行 addHandler()，同一个 logger 的 handler 列表还会不断增长；这时即使关闭传播，也可能一条记录输出多次。

把配置收敛到一个输出责任点

应用最省心的方案是只配置 root，把业务模块写成 logging.getLogger(__name__)，不在每个模块新增 handler。basicConfig() 适合简单入口；复杂应用也可以用 dictConfig()，原则仍是同一条记录只安排一个负责输出的 handler。

如果某个子系统必须写入独立文件，则让它承担完整输出责任，并明确停止向祖先传播：

import logging

logger = logging.getLogger("service.audit")

# 独立文件由这个 logger 负责，避免再交给 root handler
if not logger.handlers:
    handler = logging.FileHandler("audit.log", encoding="utf-8")
    handler.setFormatter(logging.Formatter("%(levelname)s %(message)s"))
    logger.addHandler(handler)
    logger.setLevel(logging.INFO)
    logger.propagate = False

logger.info("audit event")

两种方案不要叠加：root-only 就不要给子 logger 再加输出 handler；独立子 logger 就要设置 propagate=False。logger.disabled 不是解决重复输出的开关，它会让事件不再处理，容易把真正的问题掩盖掉。

给初始化代码加上幂等边界

重复配置常藏在“获取 logger”的辅助函数里。不要把 addHandler() 放进每次请求都会调用的路径；把日志初始化放在应用入口，或至少用明确的初始化标记。检查时还要看 handler 是否被多个模块分别创建，以及是否把同一个输出文件配置了两个 handler。

排障顺序可以固定为：先数当前 logger 的 handler，再沿 parent 走到 root；接着确认每个 handler 的类型和目标；最后查看 propagate。只改一处后再发一条唯一消息，能快速判断变化来自哪一个输出点。

常见问题

只调用一次 basicConfig()，为什么还是重复？

basicConfig() 主要配置 root；如果子 logger 之前已经有 handler，传播时仍会形成两个输出点。检查子 logger 的 handlers 和 propagate。

把 logger.setLevel(logging.ERROR) 能消除重复吗？

不能。level 决定哪些级别的记录被处理，不能合并两个 handler。重复输出应从 handler 归属和传播链解决。

库代码应该关闭 propagate 吗？

通常库不应擅自添加控制台 handler，让应用统一配置 root 更容易管理；只有库确实拥有独立输出目的地时，才由它自己配置 handler 并关闭传播。