本地进程间调用失败时，Go默认监听127.0.0.1可能导致IPv6环境（localhost解析为::1）下连接拒绝，应改用":8080"监听所有接口或"localhost:8080"自动适配双栈；Docker容器内调用宿主机服务需用host.docker.internal而非localhost，并通过环境变量配置避免硬编码。
本地进程间调用失败：监听地址写死了127.0.0.1
Go 默认 http.ListenAndServe("127.0.0.1:8080", nil) 会绑定 IPv4 回环，但某些系统或 Go 版本（尤其启用了 IPv6 的环境）下，localhost 解析为 ::1，导致连接被拒绝或超时。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 改用
http.ListenAndServe(":8080", nil)—— 空地址表示监听所有接口（包括127.0.0.1和::1） - 若需限制仅本地访问，用
http.ListenAndServe("localhost:8080", nil)，它会自动适配双栈 - 验证方式：启动服务后，在终端执行
curl -v http://localhost:8080/health和curl -v http://[::1]:8080/health都应成功
Docker 容器内调用宿主机服务失败
容器默认无法通过 localhost 访问宿主机上的服务，因为 localhost 在容器里指向容器自身，不是宿主机。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- Mac / Windows：用
host.docker.internal:8080替换代码里的localhost:8080 - Linux：启动容器时加参数
--add-host=host.docker.internal:host-gateway - 避免硬编码：把目标地址抽成环境变量，如
DOWNSTREAM_URL=http://host.docker.internal:8080 - 注意：Docker Desktop 4.19+ 对 Linux 也支持
host.docker.internal，但旧版本仍需手动加--add-host
go.mod 中模块路径与 import 路径不一致
本地联调常涉及多个服务共用同一套本地库（比如 common），但 IDE 或 go build 报错 cannot find module 或 no required module provides package，根源往往是 import 路径没对齐 go.mod 声明的模块名。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 检查项目根目录
go.mod第一行：module github.com/yourorg/service-a→ 所有import必须以该前缀开头，例如import "github.com/yourorg/common/utils" - 不要用相对路径导入（如
import "./common"），Go Modules 不认这种写法 - 本地依赖需用
replace显式映射：replace github.com/yourorg/common => ../common
，且../common下必须有合法的go.mod - 改完
go.mod后立即运行go mod tidy，否则 IDE（如 GoLand）可能仍报红
IDE 缓存未同步导致“找不到包”
即使 go build 成功，GoLand 或 VS Code 仍标红 go.opentelemetry.io/otel 这类包，提示 Cannot resolve directory，通常不是代码问题，而是 IDE 没读取到模块缓存。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 确认已配置 GOPROXY：在 IDE 设置里填入
https://goproxy.cn,direct（GoLand：Settings → Go → GOPROXY） - 强制刷新索引：GoLand 执行
File → Invalidate Caches and Restart → Invalidate and Restart；VS Code 重启 Go 扩展或整个编辑器 - 检查
$GOMODCACHE是否可读：go env GOMODCACHE输出路径下应有对应模块子目录，否则go mod download再试一次 - 别忽略
go.sum：如果删过它，go mod tidy会重生成，但可能拉到不同 commit —— 尤其当上游删了 tag，这会导致本地行为和 CI 不一致
localhost 能 curl 通，却忘了容器里根本不是同一个 localhost。 
