Go net.ListenConfig 怎样排查地址已被占用

我排查 Go 服务启动失败时，最先看的是错误发生在哪一步：如果 net.ListenConfig.Listen 还没有返回 Listener，就直接出现 address already in use，问题通常在操作系统为本地端点执行 bind 时被拒绝，而不是 Accept 或业务处理出错。

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

排查顺序可以固定为：先确认完整的 network/address，再查占用端点的 PID 和地址族，随后检查程序是否重复启动或遗漏关闭，最后才评估平台相关的复用选项。这样能避免看到“端口占用”就盲目改端口，反而掩盖部署配置问题。

最常见的结论不是 ListenConfig 失效，而是同一个本地端点已经被另一个进程、旧实例，或者同一进程的第二次初始化占用。先把“谁在监听、监听哪一族地址、什么时候创建”三件事记录下来，再决定修复方式。

先把错误定位到 bind 阶段

ListenConfig.Listen 接收上下文、network 和 address，并返回一个监听器或错误。官方文档说明，ctx 用于解析监听地址，不会影响已经返回的 Listener；而 Control 如果设置，会在创建网络连接后、绑定到操作系统之前调用。

因此，下面这个最小入口里，失败点在 lc.Listen 返回之前。不要把它和“监听成功后 Accept 循环报错”混成一个问题。

package main

import (
	"context"
	"errors"
	"fmt"
	"net"
	"syscall"
)

func openListener() (net.Listener, error) {
	// 使用固定的 network 和 address，方便把冲突端点记录到日志。
	var lc net.ListenConfig
	ln, err := lc.Listen(context.Background(), "tcp4", "127.0.0.1:8080")
	if err != nil {
		// 在常见 Unix 环境中，EADDRINUSE 表示本地端点已被占用。
		if errors.Is(err, syscall.EADDRINUSE) {
			return nil, fmt.Errorf("监听端点已占用: %w", err)
		}
		return nil, fmt.Errorf("创建监听器失败: %w", err)
	}
	return ln, nil
}

这个判断适合做分类日志，不适合替代系统监听表。错误只告诉你这次 bind 没成功，真正的占用者仍要通过 PID、监听地址和地址族来确认。

查清真正占用端点的进程

先把应用日志里的 network 和 address 原样记下来。例如 tcp、127.0.0.1:8080 与 0.0.0.0:8080 不是同一段排查信息；主机写法、端口号和地址族都可能改变结果。

在 Linux 上，可以用下面的命令查询监听表；命令只用于观察，不要把输出中的 PID 直接当成可以强制终止的对象。

# 查询 8080 端口的 TCP 监听者，并显示进程信息
ss -ltnp '( sport = :8080 )'

# 也可以用 lsof 观察监听地址和进程号
lsof -nP -iTCP:8080 -sTCP:LISTEN

如果看到旧版本服务仍在监听，优先按服务管理器的正常停止流程处理；如果是同一个程序的两个副本，检查启动脚本、进程管理器和滚动发布策略是否短时间拉起了两份实例。只有在确认进程归属后，才考虑重启或调整监听地址。

比较 tcp、tcp4 和 tcp6 的监听范围

Go 文档对 TCP network 有明确区分：tcp4 只使用 IPv4，tcp6 只使用 IPv6；使用 tcp 时，具体监听范围由系统网络栈和传入地址共同决定。空主机或未指定地址的监听还可能覆盖本机可用的多个单播/任播地址，所以“我只查了 127.0.0.1”不一定等于“没有别的监听者”。

可以用下面的代码把 network 和 address 做成显式配置，并在成功后记录实际监听地址：

package main

import (
	"context"
	"fmt"
	"net"
)

func serve(network, address string) error {
	// 让地址族成为配置的一部分，排障时能直接对照监听表。
	var lc net.ListenConfig
	ln, err := lc.Listen(context.Background(), network, address)
	if err != nil {
		return fmt.Errorf("listen %s %s: %w", network, address, err)
	}
	// Listener 不再使用时必须关闭，否则同一进程的后续初始化仍可能冲突。
	defer ln.Close()
	fmt.Println("listening on", ln.Addr().String())
	return nil
}

排查时至少分别观察 IPv4 和 IPv6：一个进程监听了通配 IPv6 地址，另一个进程再尝试覆盖同一端口时，是否冲突取决于操作系统的双栈和套接字选项。不要只根据字符串里的 localhost 推断它究竟解析成哪一族地址。

检查程序自己的生命周期

如果系统监听表没有陌生 PID，下一步就查应用自身。常见情况有三类：初始化函数被调用了两次；测试用例共享固定端口但没有串行化；旧的 Listener 没有在错误路径或退出路径关闭。

一个更容易定位的启动函数应该只创建一次监听器，记录失败参数，并让调用方负责生命周期：

func start(network, address string) (net.Listener, error) {
	// 启动阶段只负责创建一个 Listener，不在内部静默重试或换端口。
	var lc net.ListenConfig
	ln, err := lc.Listen(context.Background(), network, address)
	if err != nil {
		return nil, fmt.Errorf("start listener network=%s address=%s: %w", network, address, err)
	}
	return ln, nil
}

func run() error {
	ln, err := start("tcp4", "127.0.0.1:8080")
	if err != nil {
		return err
	}
	// 由拥有服务生命周期的函数统一关闭 Listener。
	defer ln.Close()
	return acceptLoop(ln)
}

这里没有把冲突自动改成随机端口。生产服务通常需要固定入口，随机换端口会让健康检查、反向代理或服务发现继续指向旧端口；测试场景则可以明确使用端口 0，再通过 ln.Addr() 读取系统分配的端口。

把 Control 和端口复用放到最后

ListenConfig.Control 的时机确实早于 bind，因此可以用于需要平台原生 socket 选项的场景，但它不是排查地址占用的第一步。SO_REUSEADDR、SO_REUSEPORT 的含义和可用性依赖操作系统；它们也不能证明当前服务找到了正确的旧实例，更不能安全地替代单实例约束。

如果业务确实需要端口复用，应把操作系统、网络族、部署拓扑和流量分发策略一起写进设计，并单独测试冷启动、滚动发布和异常退出。不要仅因为加了一个 socket 选项后启动成功，就认为原来的占用问题已经解决。

一张清单收敛排查

最后可以把问题压缩成一句可复现记录：某个进程在某个地址族上已经监听某个端口，而本次 ListenConfig.Listen 试图绑定重叠端点。只要这句话中的 PID、地址和时序都明确，修复通常就会落到停止旧实例、改正启动拓扑、显式区分地址族或修复 Listener 生命周期，而不是继续猜测。

相关问题

为什么把地址改成 localhost 仍然报端口占用？

localhost 可能解析到 IPv4 或 IPv6，实际范围还受系统配置影响。应记录最终使用的 network/address，并分别查看 IPv4、IPv6 监听者。

监听成功后还能通过上下文取消它吗？

不能把 Listen 的上下文当作 Listener 生命周期控制器。成功返回后，应通过关闭 Listener，并在服务层协调 Accept 循环退出。

测试为什么偶尔遇到地址已被占用？

常见原因是测试并发使用固定端口、前一个测试仍未关闭 Listener，或失败路径留下了后台 goroutine。测试可使用端口 0 并确保每个 Listener 都在结束时关闭。