Python logging.handlers RotatingFileHandler 怎样按大小保留备份日志

Python 日志文件如果一直追加，最容易出现的问题不是“写不进去”，而是单个文件越来越大，排查时也难以保留最近几轮历史。按文件大小轮转时，直接使用 logging.handlers.RotatingFileHandler：用 maxBytes 设定轮转阈值，用 backupCount 设定保留的编号备份。

官方地址：https://docs.python.org/3.15/library/logging.handlers.html

要让按大小轮转真正生效，maxBytes 和 backupCount 都不能为 0；例如 maxBytes=1024 * 1024、backupCount=3，表示当前日志接近 1 MB 时轮转，并维护有限数量的历史文件。

两个参数决定是否轮转

maxBytes 是当前日志文件的大小上限，单位是字节；backupCount 决定保留多少个带编号的旧文件。轮转后通常可以看到 app.log、app.log.1、app.log.2 等文件，旧文件达到保留数量后会被淘汰。

两个参数有一个为 0 时，文档定义的轮转不会发生。因此只设置 backupCount 而忘记设置 maxBytes，或者把 backupCount 保持为默认值，都不能达到限制文件增长的目的。

一份可复用的配置

下面的配置把处理器、格式器和 logger 连接起来。示例只负责展示标准库参数如何组合，文件路径请换成应用自己的日志目录。

import logging
from logging.handlers import RotatingFileHandler

# 按文件大小轮转，保留 3 个历史备份文件。
handler = RotatingFileHandler(
    "app.log",
    maxBytes=1024 * 1024,  # 当前文件接近 1 MiB 时允许轮转。
    backupCount=3,         # 保留 app.log.1 到 app.log.3。
    encoding="utf-8",      # 中文日志使用 UTF-8 写入。
    delay=True,            # 第一次真正写日志时再打开文件。
)

# 统一输出时间、级别和消息，便于轮转后的文件继续检索。
handler.setFormatter(logging.Formatter(
    "%(asctime)s %(levelname)s %(name)s %(message)s"
))

logger = logging.getLogger("billing")
logger.setLevel(logging.INFO)
logger.addHandler(handler)

# 业务代码只写日志，不直接管理文件名和轮转动作。
logger.info("invoice export started")

这里的关键不是把日志写到某个固定文件，而是把轮转策略交给 handler。delay=True 可以避免 logger 创建时立即打开文件；但在真正写入前，目标目录仍应提前创建，并确保进程拥有写权限。

编码、大小和并发边界

中文日志建议明确设置 encoding="utf-8"，不要依赖运行环境的默认编码。maxBytes 不是“每条日志的长度限制”，而是 handler 判断当前文件是否需要轮转时使用的文件大小阈值；backupCount 也不是压缩包数量，标准 handler 负责重命名和清理编号文件，不会自动把它们压缩成 zip。

如果多个进程同时把同一个文件交给各自的 RotatingFileHandler，轮转时可能互相覆盖或竞争文件名。这个配置适合一个进程内的常规日志写入；多进程集中写同一文件时，应把日志汇聚到单独的写入进程或选择专门的并发日志方案。

按大小还是按时间轮转

文件大小不可预测、希望单个文件不要超过某个容量时，用 RotatingFileHandler。如果更关心“每天一个文件”或“每小时切分”，则看 TimedRotatingFileHandler，它使用 when、interval 和 backupCount 描述时间策略。两者都继承自 BaseRotatingHandler，但触发轮转的条件不同，不要把按大小的 maxBytes 误写到按时间 handler 上。

常见问题

为什么文件一直不轮转？ 先确认 maxBytes 和 backupCount 都是正数，并确认实际写入的是这个 handler，而不是另一个只输出到控制台的 handler。

backupCount=3 会保留几个文件？ 它表示保留 3 个编号备份，另外还有当前的 app.log；实际文件名和轮转时机还会受当前文件是否达到阈值影响。

什么时候改用 TimedRotatingFileHandler？ 当运维要求按自然日、小时或固定时间点归档，而不是按文件大小控制容量时，按时间 handler 更贴合需求。