Go httptest 为什么端口被占用

你在用Go标准库的httptest做接口单元测试时碰到端口被占用的报错，大多不是系统里有其他外部服务抢占端口，一般是测试代码的资源释放逻辑、并行测试配置或者httptest的使用方式不当导致的。

绝大多数httptest端口占用问题，都可以通过不手动指定固定测试端口、调用完测试服务实例后主动执行Close()回收资源的方式解决，不需要额外去查找杀掉系统内的占用进程。

我第一次遇到 httptest 报端口被占用时，直觉是“随机端口撞车了”。但 Go 标准库的 httptest.NewServer 默认会在回环地址上申请系统选择的端口，真正需要优先排查的通常是固定地址覆盖、自定义监听器，或测试结束没有释放服务器。官方文档入口：https://pkg.go.dev/net/http/httptest。

先看错误地址：如果代码直接使用 NewServer，通常不是手动选端口；如果命令带了 -httptest.serve=地址、代码调用了 net.Listen，或前一个测试没有 Close，才更容易出现真正的端口冲突。

• 默认写法：NewServer 使用系统选择端口，优先保留这种方式。
• 固定端口：-httptest.serve 和自定义 net.Listen 会把冲突暴露出来。
• 生命周期：服务器创建后立即安排 defer ts.Close()，不要把清理放在容易提前返回的分支里。

先判断：到底是谁选了这个端口

标准的 NewServer 等价于创建未启动服务器再调用 Start。回环监听器默认使用类似 127.0.0.1:0 的地址，其中端口 0 表示交给操作系统选择可用端口，所以不应在测试里写死一个常用端口。

如果错误类似 listen tcp 127.0.0.1:8080: bind: address already in use，可以按下面的顺序看代码和命令：

1. 检查测试命令是否带了 -httptest.serve=127.0.0.1:8080。这个选项是给调试测试服务器用的，固定地址已有进程监听时就会失败。
2. 检查是否自己写了 net.Listen("tcp", "127.0.0.1:8080")，或把一个固定地址传给了自定义服务器。
3. 检查前一个测试是否在创建服务器后忘记 Close，尤其是带多个提前返回分支的测试。

最小配方：创建后立刻安排 Close

普通 HTTP handler 测试不需要指定端口，下面的写法把资源清理和测试主体放在同一个作用域中。这里的输出地址只是运行时生成的值，不要把它当作固定配置保存。

func TestHealth(t *testing.T) {
	// httptest 会申请系统选择的回环端口，避免和其他测试抢固定端口。
	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		// 只返回测试需要的最小响应，避免把测试和外部服务耦合。
		w.WriteHeader(http.StatusNoContent)
	}))
	// 无论断言成功、失败还是提前返回，都释放监听器和空闲连接。
	defer ts.Close()

	resp, err := ts.Client().Get(ts.URL + "/health")
	if err != nil {
		t.Fatal(err)
	}
	// 响应体也要关闭，避免客户端连接资源长时间留在池中。
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusNoContent {
		t.Fatalf("status = %d", resp.StatusCode)
	}
}

关键点不是“换一个更冷门的端口”，而是让监听器的选择权和释放责任保持在测试内部。多个测试并行运行时，系统选择端口通常比端口常量更稳妥。

需要固定端口时，先承认它是共享资源

有些调试场景确实需要从浏览器或其他进程访问测试服务器，这时可以固定端口，但应把失败视为环境冲突而不是随机重试。更可控的方式是先创建监听器，再把它交给 http.Server，由测试明确负责关闭。

func startOnPort(t *testing.T, addr string) (*http.Server, net.Listener) {
	// 固定地址只用于明确的调试场景；监听失败时直接报告真实原因。
	ln, err := net.Listen("tcp", addr)
	if err != nil {
		t.Fatalf("listen %s: %v", addr, err)
	}

	srv := &http.Server{Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		// 这个 handler 只演示固定监听器的连接入口。
		w.WriteHeader(http.StatusOK)
	})}
	go func() {
		// Serve 返回 ErrServerClosed 属于正常关闭，不应再次启动同一端口。
		if err := srv.Serve(ln); err != nil && !errors.Is(err, http.ErrServerClosed) {
			t.Errorf("serve %s: %v", addr, err)
		}
	}()
	return srv, ln
}

func TestFixedPort(t *testing.T) {
	srv, ln := startOnPort(t, "127.0.0.1:18080")
	// 先停止 HTTP 服务，再关闭监听器，避免测试结束后留下占用。
	t.Cleanup(func() {
		_ = srv.Close()
		_ = ln.Close()
	})
}

这段写法的代价是并行测试不再安全：两个测试不能同时抢同一个端口，开发机上已有服务也会造成失败。除非必须外部访问，否则仍建议回到 httptest.NewServer。

并行测试和新版本的选择

如果测试只是验证 handler，不需要真实 TCP 端口，可以使用 httptest.NewRecorder；如果需要完整客户端交互，优先使用系统选择端口。当前文档还提供了 httptest.NewTestServer 的内存网络路径，适合减少端口耗尽等瞬态网络问题，但要根据项目支持的 Go 版本决定是否采用。

常见问题

NewServer 会随机端口冲突吗？

它申请的是系统选择端口，正常情况下不应把端口常量冲突当作首要原因。先检查是否使用了 -httptest.serve、自定义监听器或未关闭旧服务器。

为什么调用 Close 仍然偶尔失败？

Close 会关闭服务器并等待正在处理的请求结束；如果测试仍有长请求或固定端口被其他进程占用，关闭旧服务器不能解决外部进程的冲突。

并行测试可以共用一个 httptest.Server 吗？

可以共用只读配置的测试服务器，但要保证 handler 和客户端使用方式是并发安全的；更简单的隔离方案是每个测试自行创建并在退出时关闭。

什么时候用 NewRecorder？

只测试 handler 的状态码、响应头和响应体时可以用它，完全绕开网络监听；需要测试真实客户端、连接或 TLS 行为时再使用服务器类 API。

排查这类问题时，先确认谁选了端口，再确认谁负责关闭，最后才考虑是否真的需要固定端口。多数测试恢复成系统选择端口并把 Close 放到创建后，就能消除“端口被占用”的重复失败。