logging.handlers.TimedRotatingFileHandler 如何按分钟轮转日志_技术教程

TimedRotatingFileHandler 默认不支持精确到分钟的轮转，因为 when='M' 表示每月而非每分钟；需设 when='S' 且 interval=60 才实现每分钟轮转，首次滚动时间取决于初始化时刻，非严格对齐整分。

为什么 `TimedRotatingFileHandler` 默认不支持精确到分钟的轮转

因为 Python 标准库中 TimedRotatingFileHandler 的 when 参数只接受特定字符串（如 'S'、'M'、'H' 等），其中 'M' 表示“每月”，不是“每分钟”——这是最常被误解的一点。真正对应“每分钟”的选项是 'S'（seconds），但需配合 interval 参数使用，否则默认是 1 秒，显然不合适。

如何用 `TimedRotatingFileHandler` 实现每分钟轮转

核心是设置 when='S' + interval=60，并确保 backupCount 合理，避免日志文件爆炸：

when='S'：触发时间单位为秒（注意不是分钟）
interval=60：每 60 秒滚动一次，即每分钟一次
utc=False（默认）：按本地时钟对齐，首次滚动时间取决于 handler 初始化时刻，不是整点；若要严格对齐到自然分钟（如 :00 秒），需重写 compute_rollover 方法
文件名后缀格式由 suffix 控制，默认是 %Y-%m-%d_%H-%M，已足够区分分钟级文件

示例初始化：

handler = logging.handlers.TimedRotatingFileHandler(
    filename='app.log',
    when='S',
    interval=60,
    backupCount=60,  # 保留最近 60 分钟的日志
    encoding='utf-8'
)

常见陷阱：轮转时间不准、文件名重复或缺失

问题往往出在初始化时机和系统时钟抖动：

如果程序启动时间是 14:23:42，第一次轮转会在 14:24:42，而不是 14:24:00 —— 这是默认行为，无法靠参数修正
多个进程同时写同一个日志路径，会导致轮转竞争，文件可能损坏；应确保单进程独占 handler，或改用 ConcurrentRotatingFileHandler 等第三方方案
delay=True 可延迟文件打开，避免无日志时提前创建空文件，但不影响轮转逻辑
Windows 下高频率轮转（如每秒）可能因文件句柄未及时释放报 PermissionError，分钟级通常无此问题

替代方案：更可控的每分钟轮转（不依赖标准库）

如果必须严格对齐到每分钟开始（如所有文件都以 _14-25 结尾），标准 TimedRotatingFileHandler 不够用。可行做法是继承它并重写两个方法：

覆盖 compute_rollover(self, curre ntTime)：将 currentTime 向下取整到最近的整分钟时间戳（currentTime // 60 * 60），再加 60
覆盖 getFilesToDelete(self)：确保清理逻辑匹配新的时间对齐方式
注意：重写后需测试 backupCount 是否仍按预期生效，尤其跨小时/跨天时边界是否正确