Python logging 日志重复打印怎么办：从 Handler 叠加到 propagate 一步步排查

一个 Python 服务上线后，排查接口问题时发现同一条日志连续出现两次，有时甚至三次。业务代码明明只调用了一次 `logger.info`，日志文件里却像被复制了一遍。这个问题不算大故障，但会让告警数量、日志体积和问题判断都变得很乱。

这篇文章我们按真实排查顺序走一遍：先复现重复日志，再看 Handler 是否被反复添加，然后检查子 logger 是否继续向父级上抛，最后把日志初始化封装成一个稳定版本。

摘要

Python logging 重复打印，通常不是 `info` 调用了多次，而是日志处理链上有多个出口。重点检查 `logger.handlers` 的数量、初始化函数是否被重复调用、`propagate` 是否导致日志继续传给父级 logger。稳定做法是只初始化一次 Handler，并在需要独立输出时关闭向上抛。

适合人群

适合正在维护 Python Web 服务、脚本任务、数据处理程序的同学。只要项目里用到了标准库 `logging`，都可以按本文方法排查。

目录

• 问题现场：明明只打一次，为什么出现两行
• 第一轮验证：Handler 是不是越加越多
• 继续定位：propagate 让日志继续向上走
• 修复方案：日志初始化只做一次
• 常见坑和最终检查

问题现场：明明只打一次，为什么出现两行

我们先复现一个最小场景。下面的 `get_logger` 每调用一次都会新建一个 `StreamHandler`，然后挂到同一个 logger 上。

import logging

def get_logger():
    logger = logging.getLogger("order")
    logger.setLevel(logging.INFO)

    handler = logging.StreamHandler()
    formatter = logging.Formatter("%(levelname)s %(message)s")
    handler.setFormatter(formatter)
    logger.addHandler(handler)
    return logger

log1 = get_logger()
log2 = get_logger()

log2.info("create order success")

运行后你可能会看到两行相同内容。我们先不急着改，先问一个问题：`log2.info` 只调用了一次，为什么会有两个出口？答案大概率在 `logger.handlers` 上。

第一轮验证：Handler 是不是越加越多

接着验证这个猜测。我们在添加 Handler 前后打印数量：

logger = logging.getLogger("order")
print("before:", len(logger.handlers))

handler = logging.StreamHandler()
logger.addHandler(handler)

print("after:", len(logger.handlers))

如果初始化函数被多次调用，数量会从 0 变 1，再变 2、3。此时一条日志会交给所有 Handler 处理，自然就重复打印。

这一步能定位第一类原因：日志初始化函数不是纯读取配置，而是每次调用都在修改同一个 logger。Web 项目热加载、任务脚本重复导入、测试用例反复创建对象时，都容易触发这个问题。

继续定位：propagate 让日志继续向上走

如果 Handler 数量只有一个，日志仍然重复，我们继续看第二条链路：子 logger 会不会把日志继续传给父级 logger。

import logging

root = logging.getLogger()
root.setLevel(logging.INFO)
root.addHandler(logging.StreamHandler())

logger = logging.getLogger("app.order")
logger.setLevel(logging.INFO)
logger.addHandler(logging.StreamHandler())

logger.info("pay success")
print("propagate:", logger.propagate)

`app.order` 自己有 Handler，根 logger 也有 Handler。如果 `propagate` 仍是默认的 `True`，这条日志会先被 `app.order` 输出一次，再继续交给上级输出一次。

这一步说明，重复日志不一定来自“重复添加 Handler”，也可能来自“日志沿层级继续上抛”。

修复方案：日志初始化只做一次

现在可以收敛方案。我们希望同一个 logger 只添加一次 Handler，并且在它需要独立输出时关闭向上抛。

import logging
from pathlib import Path

def build_logger(name: str, log_file: str | None = None) -> logging.Logger:
    logger = logging.getLogger(name)
    logger.setLevel(logging.INFO)
    logger.propagate = False

    if logger.handlers:
        return logger

    formatter = logging.Formatter(
        "%(asctime)s %(levelname)s %(name)s %(message)s"
    )

    if log_file:
        Path(log_file).parent.mkdir(parents=True, exist_ok=True)
        handler = logging.FileHandler(log_file, encoding="utf-8")
    else:
        handler = logging.StreamHandler()

    handler.setFormatter(formatter)
    logger.addHandler(handler)
    return logger

logger = build_logger("app.order", "logs/order.log")
logger.info("create order success")

这里有两个关键点：先设置 `propagate = False`，避免继续交给父级 logger；再用 `if logger.handlers` 防止重复添加 Handler。这样即使初始化函数被调用多次，也只会保留一个输出出口。

常见坑和最终检查

第一个坑是到处调用 `basicConfig`。它适合简单脚本，不适合在多个模块里反复配置。项目型代码更建议统一入口初始化。

第二个坑是库代码直接改根 logger。库函数最好拿自己的命名 logger，不要替整个应用决定日志输出方式。

第三个坑是测试环境复用进程。测试用例如果反复初始化日志，又不清理 Handler，就会越跑越多。

最后可以用一段小检查确认：

logger = logging.getLogger("app.order")
print("handler count:", len(logger.handlers))
print("propagate:", logger.propagate)
logger.info("check once")

如果 Handler 数量符合预期，`propagate` 配置明确，`check once` 只出现一行，这个日志重复问题就基本修好了。

总结

Python logging 重复打印时，我们不要先怀疑业务代码重复调用。按顺序看更快：先复现一次日志变多，再检查 Handler 数量，接着看 logger 层级是否继续上抛，最后把初始化逻辑收敛到一个函数里。

稳定的日志配置应该有清晰边界：谁负责初始化、一个 logger 有几个 Handler、是否继续传给父级，都要明确。这样日志既不会丢，也不会在排查问题时自己先把现场搅乱。