平时练习语法和调试小例子时,我们习惯使用 fmt.Println() 把变量打印到屏幕上。但在实际项目上线运行后,只打印普通文本既看不出事件发生的时间,报错时也不知道是哪一行代码出了问题,更没法按重要程度筛选信息。
为了方便记录程序运行状态与排查线上故障,Go 语言标准库内置了两套日志工具:一套是适合编写轻量脚本的传统 log 包,另一套是从 Go 1.21 版本新增的结构化日志 log/slog 包。
基础日志:log 包
在 Go 语言中,标准库 log 包的用法非常简单,常用函数名与 fmt 包基本一致。不同的是,log 包在打印每一条内容时,都会自动在最前面加上当前的日期和时间。
语法:
log.Println(v ...any)
log.Printf(format string, v ...any)
log.SetFlags(flag int)说明:
log.Println() 和 log.Printf() 分别用于普通换行打印和格式化打印。如果我们还想在日志开头显示源文件名和代码行号,可以调用 log.SetFlags() 函数组合以下 3 个常用标志常量:
- log.LstdFlags:默认标志,在日志开头输出日期和时间,如
2026/11/12 10:30:05。 - log.Lshortfile:输出简短的源文件名和代码行号,如
main.go:12,排查报错位置时非常实用。 - log.Lmicroseconds:将时间显示精度细化到微秒级。
示例 1:打印基础日志并显示行号
package main
import "log"
func main() {
// 默认只输出日期和时间
log.Println("服务正在启动...")
// 开启日期时间与简短文件名行号
log.SetFlags(log.LstdFlags | log.Lshortfile)
port := 8080
log.Printf("监听端口:%d\n", port)
}运行结果如下。
2026/11/12 10:30:05 服务正在启动...
2026/11/12 10:30:05 main.go:12: 监听端口:8080分析:
第 1 条 log.Println() 自动在消息最前面加上了当前的日期和时间。
随后我们调用 log.SetFlags(log.LstdFlags | log.Lshortfile),通过按位或运算符 | 把两个标志组合起来。这样第 2 条日志前面就多出了 main.go:12:,能帮我们快速定位这行日志是在哪个文件的第 12 行打印的。
此外,log 包还提供了 log.Fatal() 和 log.Fatalf() 函数。需要特别注意的是,调用它们打印完日志后,程序会立即调用 os.Exit(1) 强行退出,连前面登记过的 defer 语句都来不及执行。
// 推荐
log.Printf("读取配置失败:%v\n", err)
return err
// 不推荐
log.Fatalf("读取配置失败:%v\n", err)在编写普通业务函数时,遇到错误我们应该先记录日志,再正常向上返回 error。只有在 main() 函数刚启动、缺少必要配置导致服务完全无法运行时,才考虑使用 log.Fatal()。
结构化日志:log/slog 包(推荐)
传统的 log 包只负责把文字拼成一整句打印出来,既没有区分信息的轻重缓急,后期日志量大了也很难按某个用户 ID 或订单号去检索记录。
从 Go 1.21 版本开始,标准库新增了 log/slog 包,其中 slog 是英文 “structured log(结构化日志)” 的缩写。它不仅支持日志分级,还能把附带的变量按 key=value 的键值对形式整齐输出。slog 内置的 4 个日志级别如下表所示。
| 级别 | 函数 | 说明 |
|---|---|---|
| Debug(调试) | slog.Debug() | 开发调试细节(默认不输出) |
| Info(信息) | slog.Info() | 正常运行状态与关键节点记录 |
| Warn(警告) | slog.Warn() | 不影响运行但需留意的异常 |
| Error(错误) | slog.Error() | 功能执行失败的报错记录 |
语法:
slog.Info(msg string, args ...any)
slog.Warn(msg string, args ...any)
slog.Error(msg string, args ...any)说明:
这几个函数的第 1 个参数 msg 都是简短的日志说明文字。从第 2 个参数开始,我们可以按 "键1", 值1, "键2", 值2 的顺序成对传入任意多个附加字段,slog 会自动将它们拼装成 key=value 的形式打印出来。
示例 2:按级别输出结构化日志
package main
import "log/slog"
func main() {
// 打印普通信息并附带键值字段
slog.Info("用户登录成功", "user", "Lucy", "id", 1002)
// 打印警告与错误日志
slog.Warn("磁盘剩余空间较低", "freeGB", 5)
slog.Error("连接数据库失败", "host", "127.0.0.1", "retry", 3)
}运行结果如下。
2026/11/12 10:35:00 INFO 用户登录成功 user=Lucy id=1002
2026/11/12 10:35:00 WARN 磁盘剩余空间较低 freeGB=5
2026/11/12 10:35:00 ERROR 连接数据库失败 host=127.0.0.1 retry=3分析:
slog.Info("用户登录成功", "user", "Lucy", "id", 1002) 表示打印一条 INFO 级别的日志。其中 "用户登录成功" 是主消息,后面的 "user", "Lucy" 和 "id", 1002 会自动配对输出为 user=Lucy 和 id=1002。
在使用这种交替传参写法时,键名和键值必须成对出现。下面这种漏写键名的写法就是错误的。
slog.Info("订单已创建", 202601)上面代码中,202601 前面漏写了键名字符串,输出日志里就会出现 !BADKEY=202601 异常标记。如果小伙伴们希望在编译阶段就检查键值配对,也可以改写为 slog.Int("orderID", 202601) 这种指定类型的形式。
自定义日志格式、级别与行号
在示例 2 中,直接调用 slog.Info() 时默认采用传统的文本前缀格式,也不会显示代码行号。同时它默认最低只打印 Info 级别,因此直接调用 slog.Debug() 是不会显示出来的。
在实际后端开发中,我们可以通过创建日志处理器(Handler)来自定义输出格式、最低级别和代码位置。其中,slog.NewTextHandler() 会把时间和级别也统一输出为 time=... level=... 键值对文本,而 slog.NewJSONHandler() 则会输出标准的 JSON 字符串,方便日志平台自动做 JSON 解析。
语法:
opts := &slog.HandlerOptions{
Level: slog.LevelDebug,
AddSource: true,
}
logger := slog.New(slog.NewJSONHandler(os.Stdout, opts))
slog.SetDefault(logger)说明:
slog.NewJSONHandler() 的第 1 个参数用于指定输出目标,传入 os.Stdout 表示打印到控制台屏幕。第 2 个参数传入 opts 配置项,不需要修改默认配置时直接传 nil 即可。
在 slog.HandlerOptions 中,将 Level 设为 slog.LevelDebug 可以开启调试级别日志,将 AddSource 设为 true 则会自动在每条日志中附带源文件名和代码行号。
创建好 logger 对象后,我们调用 slog.SetDefault(logger) 就能将其设为全局默认日志器。之后直接调用 slog.Debug()、slog.Info() 都会按新配置输出。
示例 3:JSON 格式与 Debug 级别
package main
import (
"log/slog"
"os"
)
func main() {
// 开启 Debug 级别与代码行号,并输出 JSON 格式
opts := &slog.HandlerOptions{
Level: slog.LevelDebug,
AddSource: true,
}
logger := slog.New(slog.NewJSONHandler(os.Stdout, opts))
slog.SetDefault(logger)
slog.Debug("读取本地缓存", "key", "user_1002")
slog.Info("接口请求完成", "path", "/api/orders", "costMs", 18)
}运行结果如下。
{"time":"2026-11-12T10:40:00.123456+08:00","level":"DEBUG","source":{"function":"main.main","file":"main.go","line":17},"msg":"读取本地缓存","key":"user_1002"}
{"time":"2026-11-12T10:40:00.123500+08:00","level":"INFO","source":{"function":"main.main","file":"main.go","line":18},"msg":"接口请求完成","path":"/api/orders","costMs":18}分析:
调用 slog.SetDefault(logger) 后,每条日志都会自动输出为单行 JSON 文本,里面包含 time、level、source、msg 以及我们传入的自定义字段。
由于开启了 AddSource: true,输出中清晰记录了 main.go 的第 17 行和第 18 行,排查问题非常方便。同时,Level 设为了 slog.LevelDebug,原本默认隐藏的 slog.Debug() 日志也顺利打印了出来。
在实际项目中,同一个业务模块或同一次接口请求往往要连续打好几条日志,每次都重复传 "module", "order" 或请求编号非常麻烦。这时我们可以调用 logger.With() 派生出一个预设好公共字段的子日志器,代码如下:
orderLogger := logger.With("module", "order", "reqID", "req_9001")
orderLogger.Info("开始校验库存")
orderLogger.Info("订单创建成功", "amount", 199)使用 orderLogger 打印的每一条日志,都会自动带上 module=order 和 reqID=req_9001,既省事又能把同一次请求的所有日志串起来追踪。
提示: 在本地开发阶段,我们通常使用 slog.NewTextHandler() 并开启 slog.LevelDebug 级别,方便在终端查看调试细节。等到程序部署上线时,再切换为 slog.NewJSONHandler() 与默认的 slog.LevelInfo 级别,方便日志平台收集检索。
将日志保存到本地文件
默认情况下,无论是 log 还是 slog,都会把日志打印在控制台屏幕上。一旦关闭终端窗口,屏幕上的记录就找不到了。在实际部署服务时,我们经常需要把运行日志长期追加保存到本地的 .log 文件中。
由于 slog.NewTextHandler() 和 slog.NewJSONHandler() 的第 1 个参数都可以接收已打开的文件对象,我们只需要结合前面学过的 os.OpenFile() 函数以追加模式打开一个日志文件,再把文件对象传进去即可。由于涉及本地磁盘文件写入,小伙伴们可以在本地运行下面这个例子。
示例 4:将结构化日志写入文件
package main
import (
"fmt"
"log/slog"
"os"
)
func main() {
// 以追加模式打开或创建 app.log 文件
flags := os.O_CREATE | os.O_WRONLY | os.O_APPEND
file, err := os.OpenFile("app.log", flags, 0644)
if err != nil {
fmt.Println("打开日志文件失败:", err)
return
}
defer file.Close()
// 将日志输出目标指向 file 文件对象
logger := slog.New(slog.NewTextHandler(file, nil))
logger.Info("服务启动成功", "port", 8080)
logger.Warn("连接耗时偏高", "costMs", 350)
}在本地运行程序后,当前目录下会自动生成 app.log 文件,打开文件可以看到写入的日志记录如下。
time=2026-11-12T10:45:00.000+08:00 level=INFO msg=服务启动成功 port=8080
time=2026-11-12T10:45:00.000+08:00 level=WARN msg=连接耗时偏高 costMs=350分析:
在这个例子中,os.O_CREATE | os.O_WRONLY | os.O_APPEND 组合标志表示文件不存在时自动创建、以只写方式打开,并将新内容追加到文件末尾。确认打开文件没有报错后,大家记得写上 defer file.Close() 确保函数退出时关闭文件。
小伙伴们可以连续多运行两次程序,打开 app.log 就能看到新的日志依次追加在原有记录下方,而不会覆盖掉旧日志。
随后我们将 file 传给 slog.NewTextHandler(file, nil) 创建出 logger 对象。接下来调用 logger.Info() 和 logger.Warn() 时,日志就会直接追加写入 "app.log" 文件中,不会再打印到终端屏幕上。
如果我们在开发调试时希望日志既在终端屏幕实时显示、又同步保存到文件中,可以导入 io 包,使用 io.MultiWriter() 将两个输出目标合并起来,代码如下:
writer := io.MultiWriter(os.Stdout, file)
logger := slog.New(slog.NewTextHandler(writer, nil))常见问题
1. 平时写代码时,fmt、log 和 log/slog 这三个包应该怎么选?
我们可以根据程序规模和运行场景来区分选用:
- fmt 包:适合平时学习语法、练习算法题,或者输出直接展示给终端用户看的交互提示文字。
- log 包:适合几十行代码的单文件小脚本或临时测试工具,不需要区分日志级别时用起来最轻便。
- log/slog 包:适合正式的 Web 后端服务与多模块工程项目,自带日志分级、代码行号与键值对结构,方便线上定位问题。
2. 多个协程同时调用 slog 打印日志时,需要我们自己加锁吗?
不需要。无论是标准库传统的 log 包,还是新的 log/slog 包,它们内部在写入日志时都已经通过互斥锁做好了并发安全保护。即使多个协程在同一时刻打印日志,单条日志的内容也不会互相穿插错乱,小伙伴们可以在多协程中直接放心调用。
