Go模块管理的核心坑在于路径、命名、代理和replace等隐性规则未对齐：模块名须含域名（如example.com/myapp），replace路径需与require完全一致，GOPROXY和GOSUMDB需适配网络环境，go.sum依赖go mod tidy自动更新。
go mod 看似简单，实际在团队协作、本地开发、CI/CD 流程中极易踩坑——多数不是语法错误，而是路径、命名、代理、替换逻辑等隐性规则没对齐。
模块名必须含域名（哪怕只是假的）
常见错误：go mod init myapp 后，一加 replace 或引用子模块就报：unrecognized import path "myapp/sub" 或 dial tcp: connection refused。
原因：Go 要求模块路径必须是合法导入路径，即至少含一个 .（如 example.com/myapp），否则 Go 会尝试走 HTTPS fetch，而本地路径根本没服务器响应。
- 正确做法：用反向域名或占位域名初始化，例如
go mod init example.com/myapp - 若项目纯本地开发，也别用
localhost或127.0.0.1——它们不被 Go 视为有效主机名 - 模块名中禁止出现
@、空格、中文、下划线；只允许字母、数字、-、.、/
replace 路径错位导致循环解析失败
典型现象：go build 报错 requires a@v0.0.0: unrecognized import path "a"，即使 a 目录就在同级。
原因：replace 的目标路径是相对当前 go.mod 所在目录计算的，不是相对于被替换模块的 go.mod；且被替换模块自身的 require 必须与顶层模块路径完全一致（包括大小写和斜杠方向）。
- 确保
replace中的源模块路径（左边）和require中声明的路径完全一致，例如：require example.com/a v0.0.0→replace example.com/a v0.0.0 => ../a - 路径用
../a，不用./../a或a；Windows 下也统一用正斜杠/（Go 内部自动适配） - 执行
go mod tidy后检查生成的go.sum是否包含该本地模块的伪版本记录（形如// indirect或// local）
代理失效 + 校验和冲突引发构建中断
现象：go mod tidy 卡住、报 checksum mismatch，或 CI 中突然拉不到 golang.org/x/...。
原因：国内网络无法直连 proxy.golang.org 和 golang.org，而默认校验和数据库（GOSUMDB）又依赖这些域名做签名验证。
- 必设代理：
go env -w GOPROXY=https（推荐）或
://goproxy.cn,directhttps://mirrors.aliyun.com/goproxy/ - 私有模块跳过代理：
go env -w GOPRIVATE=git.company.com,github.com/myorg - 临时绕过校验（仅调试）：
go env -w GOSUMDB=off，但上线前务必关掉 - 清理缓存再试：
go clean -modcache，否则旧坏包可能残留
://goproxy.cn,direct多模块嵌套时 go.sum 不同步更新
现象：本地改了模块 A 的代码，B 模块 go run 仍用旧逻辑；或者 go mod vendor 后 vendor 目录里没包含 A 的最新变更。
原因：go.sum 记录的是模块**下载快照**，不是实时文件状态；replace 只影响构建时源码路径，不影响 go.sum 的哈希校验逻辑。
- 每次修改被
replace的本地模块后，必须回到主模块执行go mod tidy，触发重新计算伪版本（如v0.0.0-20260106075000-abc123） - 避免手动编辑
go.sum；它应由go mod tidy或go build自动维护 - CI 中不要
go mod vendor后再改本地模块 —— vendor 是只读快照，改了也没用
go mod init 命令输错，可能让三个人花半天对齐环境。
