Golang配置日志工具及第三方库安装教程

推荐使用 zap（高性能，适合生产）或 logrus（易上手，生态丰富）替代 Go 标准库 log；zap 需手动配置 encoder 和 WriteSyncer，支持多输出与结构化日志，logrus 提供更直观 API 和丰富 Hook。

Go 标准库的 log 包够用但功能有限，调试时往往需要更灵活的日志级别（debug/info/warn/error）、结构化输出、文件写入、滚动切割或上下文支持。推荐使用成熟第三方日志库，如 zap（高性能，适合生产）或 logrus（易上手，生态丰富）。下面以 zap 为主说明配置方法，兼顾 logrus 的轻量替代方案。

安装 zap 并初始化基础 logger

zap 是 Uber 开源的结构化、高性能日志库，分 zap（核心）和 zap/zapcore（底层控制）两层。它默认不带 console 输出的便捷封装，需手动配置 encoder 和 writer。

• 执行命令安装：go get -u go.uber.org/zap
• 最简可用配置（开发调试用）：

import "go.uber.org/zap"

func main() {
    // 快速创建开发模式 logger（带颜色、时间、行号）
    logger, _ := zap.NewDevelopment()
    defer logger.Sync() // 刷写缓冲日志，避免进程退出丢失

    logger.Info("服务启动中", zap.String("host", "localhost"), zap.Int("port", 8080))
    logger.Debug("这行只有 Debug 级别才输出")
}

注意：NewDevelopment() 适合本地调试；生产环境请用 NewProduction()，它自动禁用 debug 日志、使用 JSON 编码、写入 stderr。

自定义 zap 输出到文件 + 控制台

调试阶段常需同时看终端输出和保留完整日志文件。zap 本身不直接支持多输出，但可通过 zapcore.NewMultiCore 组合多个 WriteSyncer 实现。

• 用 os.OpenFile 创建日志文件写入器（支持追加、权限设置）
• 用 zapcore.AddSync(os.Stdout) 获取控制台写入器
• 组合两者，并指定不同 encoder（例如 console 用 human-readable，file 用 JSON）

示例片段：

func newLogger() (*zap.Logger, error) {
    // 文件写入器（自动创建目录）
    logFile, _ := os.OpenFile("app.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
    
    // 控制台和文件写入器
    consoleSyncer := zapcore.AddSync(os.Stdout)
    fileSyncer := zapcore.AddSync(logFile)

    // 定义编码器配置（console 可读，file 结构化）
    consoleEncoder := zap.NewDevelopmentEncoderConfig()
    fileEncoder := zap.NewJSONEncoder(zap.NewProductionEncoderConfig())

    // 构建两个 core
    consoleCore := zapcore.NewCore(zapcore.NewConsoleEncoder(consoleEncoder), consoleSyncer, zapcore.DebugLevel)
    fileCore := zapcore.NewCore(zapcore.NewJSONEncoder(fileEncoder), fileSyncer, zapcore.InfoLevel)

    // 合并 core，Debug 及以上发给 console，Info 及以上发给 file
    core := zapcore.NewTee(consoleCore, fileCore)

    return zap.New(core), nil
}

快速上手 logrus（适合小项目或过渡）

如果 zap 配置门槛偏高，logrus 提供更直观的 API，支持字段、Hook、格式化，且文档友好。

• 安装：go get github.com/sirupsen/logrus
• 基础用法（自动识别 terminal，彩色输出）：

import log "github.com/sirupsen/logrus"

func main() {
    log.SetLevel(log.DebugLevel)                    // 全局设为 Debug
    log.SetFormatter(&log.TextFormatter{ForceColors: true}) // 彩色终端

    log.WithFields(log.Fields{
        "user_id": 123,
        "action":  "login",
    }).Info("用户登录成功")

    log.Warn("配置未加载，使用默认值")
}

logrus 还支持 FileHook（写文件）、RotatingFileHook（按大小/时间轮转），只需额外引入对应 hook 包即可。

调试建议与常见避坑点

无论选哪个库，调试阶段注意以下几点：

• 务必调用 logger.Sync()（zap）或 log.Flush()（logrus），尤其在 main 函数末尾或进程退出前，否则最后一段日志可能丢失
• 避免在日志中拼接字符串（如 log.Info("user " + name + " login")），应使用结构化字段传参，既安全又利于后期检索
• 敏感信息（密码、token）不要打日志；如需调试，可临时开启，但提交前删掉或用 zap.String("token_masked", "***") 替代
• 在 HTTP handler 中，建议用 ctx.WithValue 注入 request ID，并通过 logger 的 With 方法透传，方便链路追踪