在Python项目开发中，日志是排查问题、监控运行状态的核心依据，但随着服务长期运行，单个日志文件会不断增大，不仅影响读取效率，还可能占满磁盘空间。RotatingFileHandler作为logging模块内置的日志处理器，能够基于文件大小自动切割日志，是处理这类问题的常用方案。
RotatingFileHandler核心参数说明
RotatingFileHandler的初始化需要传入多个关键参数，这些参数直接决定了日志切割的行为，具体参数含义如下：
| 参数名 | 参数含义 | 默认值 |
|---|---|---|
| filename | 基础日志文件名，切割后的文件会基于该名称追加后缀 | 无，必填参数 |
| mode | 文件打开模式，日志写入通常使用追加模式 | a |
| maxBytes | 单个日志文件的最大字节数，达到该值触发切割 | 0，为0时不触发大小切割 |
| backupCount | 保留的备份日志文件数量，超出数量的旧文件会被自动删除 | 0，为0时不保留备份 |
| encoding | 日志文件的编码格式，避免中文乱码问题 | None |
基础使用示例
下面是一个最简单的RotatingFileHandler配置示例，实现当日志文件达到1KB时自动切割，最多保留3个备份文件：
import logging
from logging.handlers import RotatingFileHandler
# 创建logger对象
logger = logging.getLogger("my_logger")
logger.setLevel(logging.INFO)
# 创建RotatingFileHandler实例
# 基础日志文件名为app.log，单个文件最大1024字节，最多保留3个备份
handler = RotatingFileHandler(
filename="app.log",
maxBytes=1024,
backupCount=3,
encoding="utf-8"
)
# 设置日志格式
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
handler.setFormatter(formatter)
# 给logger添加处理器
logger.addHandler(handler)
# 测试写入日志，循环写入足够多的内容触发切割
for i in range(100):
logger.info(f"这是第{i}条测试日志内容，用于验证日志切割功能是否正常工作")
切割规则说明
RotatingFileHandler的切割逻辑遵循以下规则：
- 当写入日志后，当前日志文件大小超过
maxBytes设置的值时，触发切割动作 - 切割时，原基础文件
app.log会被重命名为app.log.1，如果app.log.1已经存在，则会被重命名为app.log.2，以此类推 - 如果备份文件数量超过
backupCount设置的值，最旧的备份文件会被自动删除 - 新的日志会继续写入新生成的
app.log文件中
进阶配置注意事项
在实际项目使用中，还需要注意以下几点：
多进程场景下的限制
RotatingFileHandler不是进程安全的，如果项目是多进程架构，多个进程同时写入同一个日志文件时，可能会出现日志丢失或者文件混乱的问题，这种场景下建议使用ConcurrentLogHandler等第三方库，或者改用基于时间的TimedRotatingFileHandler配合文件锁机制。
编码格式设置
如果日志中包含中文内容，一定要设置encoding参数为utf-8，否则写入的日志可能会出现乱码，影响后续排查问题。
日志级别匹配
logger的级别和handler的级别需要合理设置，如果logger的级别高于handler的级别，那么低级别的日志不会被handler处理，也不会触发切割逻辑。
完整项目配置示例
下面是一个更贴近实际项目的日志配置示例，同时输出日志到控制台和文件，文件使用RotatingFileHandler进行切割：
import logging
from logging.handlers import RotatingFileHandler
def setup_logger():
# 创建logger
logger = logging.getLogger("project_logger")
logger.setLevel(logging.DEBUG)
# 避免重复添加handler
if logger.handlers:
return logger
# 控制台handler
console_handler = logging.StreamHandler()
console_handler.setLevel(logging.INFO)
console_formatter = logging.Formatter('%(asctime)s - %(levelname)s - %(message)s')
console_handler.setFormatter(console_formatter)
# 文件handler，使用RotatingFileHandler
file_handler = RotatingFileHandler(
filename="logs/project.log",
maxBytes=10 * 1024 * 1024, # 单个文件最大10MB
backupCount=10, # 保留10个备份
encoding="utf-8"
)
file_handler.setLevel(logging.DEBUG)
file_formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(filename)s - %(lineno)d - %(message)s')
file_handler.setFormatter(file_formatter)
# 添加handler到logger
logger.addHandler(console_handler)
logger.addHandler(file_handler)
return logger
if __name__ == "__main__":
logger = setup_logger()
logger.info("项目启动成功")
logger.debug("这是一条调试级别的日志")
# 模拟业务日志写入
for i in range(500):
logger.info(f"处理第{i}笔业务，状态正常")
通过上面的配置，项目运行过程中的日志会自动按大小切割，既不会让单个日志文件过大，也不会无限制占用磁盘空间，能够有效降低日志管理的成本。
PythonRotatingFileHandler日志切割logging模块修改时间：2026-06-12 23:48:23