Python 日志配置怎么选：basicConfig、dictConfig 与分层输出的取舍

Python 日志一旦从单文件脚本长到多个模块，最先变得混乱的通常不是日志级别，而是配置入口：有的模块自己调用 basicConfig()，有的模块直接加 StreamHandler，结果同一条记录打印两遍，或者线上只有 ERROR 没有 INFO。选型时可以先记住一个边界：一次性脚本用 basicConfig() 就够，多模块应用把配置集中到 dictConfig()，而分层输出要靠 logger、handler 和 propagation 一起设计。

最小选择规则是：脚本优先 basicConfig，服务优先集中式 dictConfig，需要把业务日志和审计/错误日志分开时，再增加不同 handler；不要让每个业务模块各自改 root logger。

先按运行场景缩小选择范围

如果程序只有一个入口、没有复用模块，而且日志只需要输出到终端，basicConfig() 是成本最低的方案。它适合临时数据处理脚本、一次性迁移命令和本地实验。代码短，读者也能立刻看懂默认级别、格式和输出位置。

import logging

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s %(levelname)s %(name)s: %(message)s",
)
logger = logging.getLogger(__name__)
logger.info("开始读取配置")

但脚本一旦被别的模块导入，或者测试框架已经提前给 root logger 加了 handler，basicConfig() 可能不会产生你期待的变化。这个行为不是随机的，而是它默认不覆盖已有 handler。

三个方案分别解决什么问题

basicConfig：给小程序一个默认起点

basicConfig() 适合“全局只有一套规则”的程序。它可以快速设置级别、格式、文件名和输出流，但不适合在多个业务模块里反复调用。模块 import 顺序一变，谁先初始化 root logger 就可能影响后面的配置。

dictConfig：把全局规则变成可检查的配置

logging.config.dictConfig() 适合服务、定时任务和多模块命令行工具。handler、formatter、logger、root 等对象都可以在一个字典里声明，代码负责加载配置，业务模块只负责产生日志。

import logging
import logging.config

LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "formatters": {
        "plain": {"format": "%(asctime)s %(levelname)s %(name)s: %(message)s"}
    },
    "handlers": {
        "console": {"class": "logging.StreamHandler", "formatter": "plain"}
    },
    "root": {"level": "INFO", "handlers": ["console"]},
}

logging.config.dictConfig(LOGGING)
logger = logging.getLogger("orders.sync")
logger.info("同步任务已启动")

这里的 disable_existing_loggers=False 是一个值得显式写出的判断。它能避免配置过程把已经创建的非 root logger 静默禁用，尤其适合项目里还存在第三方库日志的情况。是否保留它要结合应用边界决定，不要把配置样例当成永远正确的开关。

分层输出：当不同日志需要不同去处

如果应用需要把普通运行日志输出到终端，把错误和审计事件写入单独文件，就需要按 logger 和 handler 分层。logger 决定记录的来源归属，handler 决定日志的写入位置，formatter 决定日志的输出格式，level 决定哪些日志能通过过滤门槛。

用四个维度比较配置方案

选型不要只看代码行数，至少对比四个维度：配置是否集中管控、模块逻辑是否容易复用、输出链路是否支持分流、初始化顺序是否会影响最终记录结果。

• 配置集中度：basicConfig 适合单入口；dictConfig 更适合把规则放在一个显式边界。
• 模块复用：业务模块只调用 getLogger(__name__)，不要在 import 时配置 root logger。
• 输出分流：只需要单一终端输出的场景用基础配置即可，涉及多目标输出的场景就配置多个 handler，同时为专用 logger 划定清晰的作用边界。
• 可测试性：做日志相关测试时，要校验实际挂载的 handler、日志级别是否匹配、是否存在重复输出的条目，而不是只校验「代码调用过 logger.info」。

多模块服务推荐的最小结构

可长期维护的项目结构一般会把日志配置统一放在程序入口，业务模块里只初始化对应自己模块的 logger：

# orders/sync.py
import logging

logger = logging.getLogger(__name__)

def sync_once() -> None:
    logger.info("开始同步订单")

# main.py
from orders.sync import sync_once
from project_logging import configure_logging

configure_logging()
sync_once()

如果业务模块在导入阶段就执行日志输出，入口的配置逻辑还没来得及运行，日志记录就会走临时的默认行为。更稳妥的做法是让模块先定义好函数和 logger 对象，真正的业务执行逻辑放在全局配置完成之后再运行。

当专用 logger 自己挂了 handler，又没有关闭传播时，记录可能先被专用 handler 处理，再沿父级一路到 root handler，于是终端出现两份。解决方式不是盲目删 handler，而是明确选择：让它只交给 root 处理，或者设置 logger.propagate = False，再由专用 handler 独立负责。

basicConfig 看似没生效时怎么验证

遇到日志行为不符合预期时，先不要反复修改日志格式和过滤级别，先直接查看 root logger 当前的生效状态：

import logging

root = logging.getLogger()
print(root.level)
print(root.handlers)

如果 root.handlers 已经非空，重复调用 basicConfig() 默认不会重置它。只有在你确认程序拥有配置控制权、并且确实要覆盖旧 handler 时，才考虑显式使用 force=True。库代码不应该擅自替应用重置全局日志。

哪些场景不该急着上 dictConfig

如果只是行数不到百行的本地小脚本，直接写一长串包含 formatter、handler、logger 的配置字典反而会增加代码阅读负担。日志的配置复杂度应该由实际的输出目标数量和业务模块规模推动，不要盲从「服务端项目都该用配置字典」这类不成文经验。

同样，不要为了实现所谓的分层效果，给每个业务模块都单独挂载一个 handler。挂载的 handler 越多，出现重复输出、程序退出时资源关闭顺序异常的问题越难排查验收。先让所有日志统一走 root 的配置，只对那些真正需要单独落盘、单独采集或者单独权限管控的事件，新增对应的专用 handler。

发布前做一组可重复的验收

调试验证环节建议准备正常运行日志、错误日志和专用 logger 的事件三类测试内容，逐一检查三件事：每条日志记录的出现次数是否符合预期、格式里附带的 logger 名称是否正确、级别过滤规则是否正常生效。之后再切换到已经初始化过其他 handler 的测试环境重新运行一遍，确认改变初始化顺序后不会悄无声息丢失日志。

def test_logging_shape(caplog):
    logger = logging.getLogger("orders.sync")
    with caplog.at_level(logging.INFO, logger="orders.sync"):
        logger.info("one record")
    assert [item.message for item in caplog.records] == ["one record"]

验收的结果最好同步记录在测试或者运行手册里：哪些 logger 走默认的 root 链路、哪些 logger 挂载了专用 handler、哪些节点主动关闭了日志向上传播，以及修改日志配置后的回滚步骤。只看终端上「好像有日志输出」远远不够。

常见问题

为什么 basicConfig 调用了但格式没变？

最常见原因是 root logger 已经有 handler。先检查 logging.getLogger().handlers，确认配置时机，再决定是否由应用入口使用 force=True 覆盖旧配置。

业务模块应该直接配置日志吗？

通常不建议这么做。业务模块只需要创建对应自己模块的命名 logger 并记录事件即可，全局的 handler 和输出格式统一交给应用入口管控；这样导入第三方模块时不会意外改变宿主程序的原有日志策略。

日志重复打印先查什么？

先数专用 logger 和祖先 logger 上的 handler，再确认 propagate 是否让记录继续向 root 传递。通常是“专用 handler + root handler”同时生效导致重复。

把选择结果留成一条规则

单入口、单输出的脚本从 basicConfig 开始；多模块或需要审查配置的服务使用 dictConfig；只有当日志确实需要不同输出目标时才引入分层 handler。最后用 handler 数量、重复条数、级别过滤和初始化顺序做验收，这比凭经验选择某个 API 更可靠。