Go http.Server.ErrorLog 怎样接管服务器内部错误输出

在 Go HTTP 服务接入统一日志系统时，我更愿意先把日志分成两条线：一条记录每个请求的访问结果，另一条只接收服务器自身在接收连接、运行 Handler 或访问底层文件系统时遇到的内部问题。后一条就是 http.Server.ErrorLog 的职责。

直接结论：创建一个 *log.Logger，把它赋给 Server.ErrorLog，就能接管服务器内部错误输出；如果保持 ErrorLog: nil，net/http 会使用 log 包的标准 logger。它不会自动变成访问日志中间件，也不会替你记录每个请求的状态码。

官方资料：https://pkg.go.dev/net/http#Server

一、先划清 ErrorLog 的职责边界

这个字段的名字很容易让人误解成“所有 HTTP 日志”。官方文档给出的范围是：接收连接失败、Handler 的异常行为，以及底层 FileSystem 错误。换句话说，它服务的是服务器运行机制，而不是业务请求指标。

这一步很重要：如果把访问日志也塞进同一个 Logger，后面接入采集系统时就很难判断一条记录是“请求慢”还是“服务器无法接收连接”。职责分开，前缀和字段才有稳定含义。

二、准备一个可复用的 log.Logger

ErrorLog 的类型是 *log.Logger，最常见的接管方式是让它写入项目已有的输出目标。下面示例把输出写到标准错误流，并加上 http-server 前缀，便于容器日志或进程管理器后续筛选。

package main

import (
	"log"
	"os"
)

func newServerErrorLogger() *log.Logger {
	// 使用 stderr 承载服务器级错误，避免和业务响应或标准输出混在一起。
	return log.New(
		os.Stderr,
		"http-server: ",
		log.Ldate|log.Ltime|log.Lmicroseconds,
	)
}

如果项目已经有文件、轮转器或集中式写入器，只要它实现 io.Writer，就可以把它作为第一个参数传给 log.New。时间标志由 Logger 统一添加，正文里不要再手工拼接时间，避免同一条记录出现两套时间。

这里的前缀用于区分日志来源，不等于访问日志字段。想要记录请求路径、方法、状态码和耗时，仍然应该在 Handler 外包一层中间件，由中间件用另一个 logger 或结构化日志组件输出。

三、把 Logger 注入 http.Server

创建服务器时直接设置 ErrorLog，接管关系就清楚了。下面的示例保留一个普通 Handler，只展示日志接线位置；它没有把请求访问记录伪装成 ErrorLog。

package main

import (
	"log"
	"net/http"
	"os"
)

func main() {
	// 统一收集 net/http 自身的内部错误。
	serverLogger := log.New(os.Stderr, "http-server: ", log.LstdFlags)

	mux := http.NewServeMux()
	mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
		// 访问日志不在这里由 ErrorLog 负责，业务 Handler 只处理响应。
		w.WriteHeader(http.StatusNoContent)
	})

	srv := &http.Server{
		Addr:     ":8080",
		Handler:  mux,
		ErrorLog: serverLogger,
	}

	// Serve 的启动或关闭错误仍由应用生命周期代码单独处理。
	if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
		serverLogger.Printf("server lifecycle error: %v", err)
	}
}

从责任链看，服务器内部的错误会经过 serverLogger；而 ListenAndServe 返回的错误仍然由调用方决定如何处理。这样做能避免一个常见误区：以为配置了 ErrorLog 后，所有启动、关闭和业务错误都会自动进入同一处。

四、处理 nil 默认行为与上线流程

当 ErrorLog 为 nil 时，文档规定会通过 log 包的标准 logger 输出。小型程序或一次性工具可以依赖这个默认值；服务进入统一采集环境后，显式配置通常更容易维护，因为输出目标和前缀都写在 Server 初始化处。

我会按下面的顺序把它放进上线流程：

1. 先定义边界：确认采集器要接收的是服务器内部错误，而不是每条访问记录。
2. 再确定目标：选择标准错误、文件轮转器或项目日志适配器，并保证写入器的生命周期长于 Server。
3. 最后注入：在构造 http.Server 时设置 ErrorLog，不要在多个启动分支里分别创建不同 Logger。
4. 检查关闭路径：如果写入器需要关闭或刷新，应用退出时要先完成 Server 的关闭，再处理日志目标。

还有三个容易踩到的坑：

• 不要把 log.Fatal 直接用于可恢复的服务器内部错误处理；它会终止进程，破坏上层的重试或优雅关闭策略。
• 不要把同一个访问日志中间件再挂到 ErrorLog 上，否则一条请求可能在访问日志和错误日志里重复出现。
• 不要把 ListenAndServe 返回的 http.ErrServerClosed 当成故障；优雅关闭时它是正常的生命周期结果。

五、速查表：什么时候设置，什么时候保留 nil

如果只记住一句话：Server.ErrorLog 是“服务器内部问题的接收器”，不是“HTTP 请求流水账”。用 log.New 创建一个有明确输出目标的 Logger，再在 Server 初始化时注入，日志边界和故障定位都会稳定很多。

常见问题

ErrorLog 能记录每个请求的状态码吗？

不能把它当作访问日志使用。状态码、路径和耗时应由访问日志中间件记录，ErrorLog 只覆盖 Server 文档定义的内部错误范围。

ErrorLog 为 nil 会不会完全没有日志？

不会。nil 时会使用 log 包的标准 logger；如果采集器只监听项目自定义输出目标，才可能出现“看不到”的运维错觉。

为什么配置了 ErrorLog 还要处理 ListenAndServe 返回值？

因为返回值属于 Server 生命周期控制流，和内部错误日志不是同一条接口。启动失败、优雅关闭和监听器关闭结果，都应该由调用方显式判断。