Go程序启动报“Address family not supported by protocol”可锁定为IPv6绑定失败,主因是系统禁用IPv6(/proc/sys/net/ipv6/conf/all/disable_ipv6=1)而代码或依赖库仍尝试AF_INET6 socket;修复方式是显式使用"0.0.0.0:端口"替代""或"[::]:端口",避免隐式IPv6回退。

Go 程序启动时出现 Address family not supported by protocol,基本可以锁定是 socket 绑定阶段对 IPv6 地址(如 [::] 或 ::1)的使用与当前系统不兼容 —— 最常见原因是系统禁用了 IPv6,但代码或依赖库仍尝试用 AF_INET6 创建 socket。
为什么 Go 会触发这个错误
Go 的 net 包在监听地址时,若传入的是带方括号的 IPv6 字符串(如 "[::]:8080"),底层会调用 socket(AF_INET6, ...)。一旦内核禁用 IPv6(例如通过 ipv6.disable=1 启动参数),该系统调用就直接返回 EAFNOSUPPORT,Go 将其转为 "Address family not supported by protocol" 错误。
注意:这不是 Go 本身的 bug,而是程序行为与运行环境不匹配。即使代码里没显式写 [::],某些库(如 gin.Default()、http.ListenAndServe 传空地址)也会默认 fallback 到 IPv6 wildcards。
- 检查是否禁用 IPv6:
cat /proc/sys/net/ipv6/conf/all/disable_ipv6返回1即已禁用 - Go 的
http.ListenAndServe("", handler)在无显式地址时,会尝试[::]:http→ 触发失败 - 第三方 Web 框架(如
echo、fiber)若未指定0.0.0.0,也可能走同样逻辑
如何快速验证并修复 Go 监听逻辑
最直接的办法是强制使用 IPv4 地址字面量,绕过 IPv6 探测路径。
- 把
http.ListenAndServe(":8080", handler)改成http.ListenAndServe("0.0.0.0:8080", handler) - 如果用
net.Listen("tcp", ":8080"),同样改为net.Listen("tcp", "0.0.0.0:8080") - 框架初始化时留意文档:比如
gin的router.Run()默认用:8080,应显式传"0.0.0.0:8080" - 避免使用
[::]、::1、[::1]等 IPv6 格式字符串作为监听地址
改完后无需重启系统或修改内核参数,立刻生效。
排查依赖库或中间件是否偷偷用了 IPv6
有些 Go 库(尤其是封装了健康检查、metrics、pprof 的组件)会在后台自动监听 [::]:6060 这类地址。错误堆栈里若出现 net/http.(*Server).Serve 但没找到你自己的监听代码,就要怀疑这类“隐式监听”。
- 全局搜索项目中是否含
"[::]"、"::1"、"0.0.0.0"以外的监听地址字面量 - 检查
import的第三方包文档,例如prometheus/client_golang的http.Handler示例常默认绑定[::]:9090 - 用
lsof -i -P -n | grep LISTEN查看进程实际监听的地址族,确认是否真有tcp6条目 - 临时加
log.Printf("listening on %s", addr)打印所有net.Listen的输入地址
要不要启用系统 IPv6
不推荐仅为此开启 IPv6 —— 尤其在生产服务器上。IPv6 全局启用涉及内核参数、防火墙规则、网络设备配置,容易引入新问题。而且绝大多数 Go 服务只需 IPv4 就够用。
真正需要 IPv6 的场景(如必须对接只支持 IPv6 的下游),再按需启用;否则,坚持用 0.0.0.0 显式指定 IPv4 是更轻量、更可控的做法。很多团队在线上环境长期禁用 IPv6,就是出于运维确定性考虑。


















