macOS端口连接失败常因服务仅监听127.0.0.1而系统优先尝试IPv6的::1，需确认lsof输出含IPv6监听、改服务绑定::1或0.0.0.0，或临时注释/etc/hosts中::1 localhost行。
macos 开发中端口连接失败常与 ipv6 行为有关，不是因为 ipv6 本身有问题，而是系统在双栈环境下优先尝试 ipv6 地址，而本地服务（如 node.js、python flask、rails、docker 容器等）默认只监听 127.0.0.1（ipv4 loopback），未绑定 ::1（ipv6 loopback），导致请求被拒绝或超时。
确认服务是否监听 IPv6 回环地址
运行服务后，在终端执行：
lsof -iTCP -sTCP:LISTEN -P | grep :你的端口号
观察输出中是否有 localhost:端口 或 *:端口，更关键的是看协议列是否含 IPv6。若只有 IPv4 且地址为 127.0.0.1，说明服务未响应 IPv6 请求。
常见修复方式：
- Node.js：启动时指定
--host ::1或代码中用server.listen(3000, '::1')；更稳妥是监听0.0.0.0（IPv4）和::（IPv6），但开发环境建议明确指定 - Python Flask：加参数
--host=::1 --port=5000，或代码中app.run(host='::1', port=5000) - Rails：启动加
-b ::1，例如rails server -b ::1 -p 3000 - Docker：确保容器内服务监听
[::]:端口，且docker run不强制绑定127.0.0.1；宿主机访问时用curl -g http://[::1]:3000测试 IPv6 路径
临时绕过 IPv6 优先行为
若服务暂不支持 IPv6，又需快速验证功能，可让 macOS 在解析 localhost 时只返回 IPv4：
编辑 /etc/hosts，确保这一行在顶部且未被注释：
127.0.0.1 localhost
删除或注释掉下面这行（如果存在）：
::1 localhost
保存后无需重启，多数应用下次 DNS 解析即生效。注意：此操作不影响其他域名或实际网络通信，仅限本机回环解析。
检查浏览器或工具是否强制走 IPv6
某些前端调试场景（如 Chrome DevTools Network 面板、Postman、curl）可能因系统策略或配置优先使用 IPv6。验证方法：
- 用
curl -v http://localhost:3000查看实际连接的 IP（看* Connected to localhost (127.0.0.1)还是(::1)） - 改用
curl -4 http://localhost:3000强制 IPv4，或curl -6 http://localhost:3000强制 IPv6 测试差异 - Chrome 地址栏输入
chrome://net-internals/#dns，点击“Clear host cache”清除 DNS 缓存，避免旧解析干扰
避免全局禁用 IPv6 带来的副作用
虽然 sudo networksetup -setv6off Wi-Fi 或关闭系统设置里的 IPv6 能“解决”问题，但会连带影响 AirDrop、Handoff、Continuity 等依赖 IPv6 的系统服务，且不符合现代网络实践。开发阶段应优先适配双栈，而非降级回避。
真正需要禁用时，也建议只针对当前网络服务（如仅关 Wi-Fi 的 IPv6），并保留以太网或蓝牙 PAN 的 IPv6 能力，保持灵活性。
