Go Lumberjack 怎样按文件大小配置日志轮转

我第一次把服务日志从标准输出切到文件时，最先遇到的不是“怎么写日志”，而是日志文件会不会一直长下去。Go Lumberjack 的定位很克制：它实现一个可接入 io.Writer 的滚动文件写入器，按 MaxSize 以 MB 为单位控制当前文件的大小。达到轮转边界后，它关闭当前文件、改名保留，再创建原文件名作为新的当前日志。

官方地址：https://github.com/natefinch/lumberjack

按文件大小轮转的核心配置是 MaxSize。把它放进 lumberjack.Logger，再交给 log.SetOutput 或其他能写入 io.Writer 的日志组件即可；旧文件要不要保留、压缩多久，另由 MaxBackups、MaxAge 和 Compress 决定。

• v2 使用 gopkg.in/natefinch/lumberjack.v2 导入路径，包名仍是 lumberjack。
• MaxSize: 100 表示当前日志文件达到 100 MB 的大小边界；官方默认值也是 100 MB。
• Lumberjack 是日志栈底部的文件写入组件，不负责结构化字段、检索、告警或多进程协调。

先把“按大小轮转”理解准确

这里的大小不是“每隔一段时间检查一次”的近似策略，而是发生在写入路径上：如果一次写入会让当前文件超过 MaxSize，Lumberjack 会先关闭并改名当前文件，再创建原始文件名继续写入。于是，应用始终可以把 Filename 看作当前日志，带时间戳的文件则是历史备份。

这个语义也带来一个容易忽略的边界：如果一次写入本身就大于 MaxSize，Write 会返回错误。MaxSize 不是把任意超长消息自动切片的参数，调用方仍要处理日志组件返回的写入错误。

用 MaxSize 接入标准库 log

下面是一个最小但可继续扩展的接入方式。示例把轮转阈值写成 200 MB，同时启用历史文件 gzip 压缩。中文注释只解释关键配置和资源边界，避免把每一行都改写成注释。

package main

import (
    "log"

    "gopkg.in/natefinch/lumberjack.v2"
)

func main() {
    // Logger 是 io.Writer；当前文件达到 200 MB 的写入边界时触发轮转。
    rollingFile := &lumberjack.Logger{
        Filename: "/var/log/myapp/app.log",
        MaxSize:  200, // 单位是 MB，不是字节。
        Compress: true, // 轮转后的历史文件使用 gzip 压缩。
    }

    // 标准库 log 直接把后续输出交给 Lumberjack。
    log.SetOutput(rollingFile)
    log.Println("服务已启动")
}

如果只需要按大小轮转，保留 Filename 和 MaxSize 就够了。实际项目中通常还会把 MaxBackups、MaxAge 一起写上，避免磁盘上的历史文件无限增长；是否启用 Compress 则要结合排障时读取旧日志的习惯。

历史文件怎样按数量和时间收敛

轮转本身只解决“当前文件太大”的问题，清理旧文件是另一层策略。MaxBackups 限制保留的旧文件数量，MaxAge 按文件名中记录的轮转时间保留天数；两者都为 0 时，不会基于这两个字段删除旧文件。开启 Compress 后，轮转文件以 gzip 形式压缩，但它不改变大小阈值的含义。

我会特别注意的三个边界

不要让多个进程共用同一份配置

官方明确假设只有一个进程写入这些输出文件。多个进程同时使用相同的 Lumberjack 配置，可能造成轮转和文件状态不正确。多实例服务应让每个实例使用独立文件，或把日志交给专门的采集组件处理。

当前文件名和备份文件名不是一回事

轮转后的备份会在扩展名前加入时间戳，例如 app-2026-10-29T18-30-00.000.log。应用继续写入原来的 app.log，不要在业务代码里把带时间戳的备份当成当前文件。

主动轮转不等于按大小轮转

如果应用收到 SIGHUP 等信号，需要立即切换文件，可以保存 Logger 指针并调用 Rotate()。这属于额外的主动动作，和写入超过 MaxSize 的自动轮转是两种触发来源。

// 只在应用明确要求立即切换文件时主动轮转。
if err := rollingFile.Rotate(); err != nil {
    // 轮转失败要交给应用的错误处理或告警链路。
    log.Printf("日志主动轮转失败: %v", err)
}

结论

Go Lumberjack 按文件大小配置日志轮转，核心就是在 lumberjack.Logger 中设置 Filename 和以 MB 为单位的 MaxSize，再把它接到日志组件的 io.Writer。在此基础上，用 MaxBackups 和 MaxAge 控制历史文件，用 Compress 换取磁盘空间；如果存在多进程写入或集中采集需求，就不要把这一个组件当成完整日志系统。

相关问题

MaxSize 写 200 是 200 字节吗？

不是，官方字段说明的单位是 MB。它控制当前日志文件的大小边界，不能替代单条日志大小限制或消息切分。

MaxBackups 和 MaxAge 必须同时配置吗？

不必须。可以只按数量保留，也可以只按轮转时间保留；两者都设置时，旧文件可能因任一条件达到而被清理。

为什么配置后没有立即生成新文件？

Lumberjack 在首次写入时打开文件，只有后续写入会使当前文件超过 MaxSize 时才触发自动轮转。若要立即切换，可以保存 Logger 并显式调用 Rotate()。