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 必须与顶层模块路径完全一致（包括大小写和斜杠方向）。
立即学习“go语言免费学习笔记（深入）”；
拥有企业网站常用的模块功能：企业简介模块、联系我们模块、新闻(文章)模块、产品模块、图片模块、招聘模块、在线留言、反馈系统、在线交流、友情链接、网站地图、栏目管理、网站碎片、管理员与权限管理等等，所有模块的分类均支持无限级别的分类，可拓展性非常强大。其中包括万能的栏目管理系统、网站碎片管理系统，通过这些系统，可以组合出各种不同的页面和应用。系统带强大灵活的后台管理功能、支持伪静态URL页面功能、自
- 确保
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,direct（推荐）或https://mirrors.aliyun.com/goproxy/ - 私有模块跳过代理：
go env -w GOPRIVATE=git.company.com,github.com/myorg - 临时绕过校验（仅调试）：
go env -w GOSUMDB=off，但上线前务必关掉 - 清理缓存再试：
go clean -modcache，否则旧坏包可能残留
多模块嵌套时 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 命令输错，可能让三个人花半天对齐环境。 
