Django日志配置与按天轮转设置

Django日志配置看似简单，实则暗藏多个极易被忽略的关键细节：必须显式声明`"version": 1`（整数而非字符串），否则整个LOGGING配置将被静默忽略；实现按天轮转需严格使用`TimedRotatingFileHandler`并设置`"when": "midnight"`，而非按大小轮转的`RotatingFileHandler`；loggers必须手动绑定handlers，root logger（`""`）也不例外；此外，文件路径须用绝对路径、运行用户需具备目录写权限、时区偏差可能导致轮转时间错乱——这些底层运维细节往往在上线后才暴露，成为深夜排查的“隐形杀手”。

LOGGING 字典必须定义 version 且值为 1

不写或写错 version，Django 启动时不会报错，但整个 LOGGING 配置会被静默忽略——日志照常输出到 console，但你配的文件路径、轮转、过滤器全无效。

这是最常被跳过的初始化前提。Django 的日志系统依赖 Python 标准库 logging.config.dictConfig，它强制要求 version 键存在且等于 1。

• version 必须是整数 1，不是字符串 "1"
• 哪怕只配一个 handler，也要先写 "version": 1
• 如果用了 disable_existing_loggers: True，还要确认是否意外关掉了 Django 内部 logger（比如 django.request）

按天轮转得用 TimedRotatingFileHandler，不是 RotatingFileHandler

RotatingFileHandler 是按大小轮转，TimedRotatingFileHandler 才支持按天、按小时等时间维度。想实现 “每天一个日志文件”，必须选后者，并正确设置 when 和 interval。

常见错误是只写 "when": "midnight" 却漏掉 "backupCount" 或误设 "interval": 1（它对 when="midnight" 实际无效）。

• "when": "midnight" 表示每天凌晨 0 点触发轮转（推荐，语义明确）
• "interval": 1 在 when="midnight" 下可省略，但写了也不影响；若用 "when": "D"，则 interval 表示间隔天数
• "backupCount": 30 控制最多保留多少个历史文件，不设则无限累积
• "encoding": "utf-8" 建议显式指定，避免中文日志乱码

"handlers": {
    "file": {
        "level": "INFO",
        "class": "logging.handlers.TimedRotatingFileHandler",
        "filename": "/var/log/myapp/django.log",
        "when": "midnight",
        "backupCount": 30,
        "encoding": "utf-8",
        "formatter": "verbose"
    }
}

Django 的 LOGGING 配置里，loggers 要显式绑定 handler

很多人以为只要配了 handler 就自动生效，其实不然。Django 的 logger 层级是树状结构，""（空字符串）是 root logger，但 Django 默认没把它和你的文件 handler 绑定——所以即使配置了 TimedRotatingFileHandler，日志也不会进文件。

必须在 loggers 下明确声明哪些 logger 使用哪个 handler，尤其要注意 django.request、django.db.backends 这类关键子 logger。

• 想让所有日志都进文件？给 root logger 绑定："" 键下设 "handlers": ["file"]
• 只想记录请求异常？单独配 "django.request"，并设 "propagate": False 防止重复输出
• DEBUG=True 时，console handler 仍会输出，可临时注释掉或用 "level": "WARNING" 降噪

"loggers": {
    "": {
        "handlers": ["file", "console"],
        "level": "INFO",
        "propagate": False
    },
    "django.request": {
        "handlers": ["file"],
        "level": "ERROR",
        "propagate": False
    }
}

权限、路径、时区三个实际运行时坑点

配置写对了，服务跑起来却没生成日志文件？大概率卡在这三处。

• 运行 Django 的用户（如 www-data）必须对 filename 所在目录有写权限，且父目录存在——Django 不会自动创建多级路径
• filename 路径别用相对路径（如 "logs/django.log"），Django 启动位置不确定，容易写到奇怪地方；统一用绝对路径
• TimedRotatingFileHandler 按服务器本地时间轮转，如果服务器时区 ≠ 业务时区（比如服务器 UTC、业务需东八区），轮转时间会偏差 8 小时；解决办法是：要么改服务器时区，要么用 logging.handlers.TimedRotatingFileHandler 的 utc=True + 应用层补偏移（不推荐），更稳的是用第三方 concurrent-log-handler 或 logrotate 外部管理

轮转逻辑本身不复杂，但文件系统权限、路径解析、时区对齐这些底层细节，才是上线后最常打断你深夜排查的点。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~