模块路径必须与代码托管地址严格一致，主版本≥2时须含/vN后缀，私有模块需配置GOPRIVATE和git url重写，版本号须带v前缀且符合语义化规范。
Go 项目里依赖导入路径和版本控制不是“设好就完事”的配置项，而是直接影响构建稳定性、跨团队协作效率和升级安全性的关键环节。核心原则只有一条：模块路径必须可解析、可验证、可复现，否则 go build 或 go test 在不同机器上可能拉到完全不同的代码。
模块路径怎么写才不会被 go mod tidy 报错
模块路径不是随便起的别名，它直接决定 import 语句能否被 Go 工具链正确解析，也影响私有模块代理能否命中。
- 必须与代码实际托管地址一致（如 GitHub 仓库 URL 的路径部分），例如仓库地址是
https://github.com/myorg/backend，则go mod init github.com/myorg/backend - 不能省略域名，
myproject或backend这类纯名称会导致go get失败或误导向本地 GOPATH - 主版本号必须显式体现在路径中（仅当 v2+），例如 v2 版本应声明为
github.com/myorg/backend/v2，否则 Go 会拒绝加载 v2+ 依赖 - 若用私有 Git 服务（如 Gitea、GitLab），需配合
GOPROXY和git config设置跳过 HTTPS 验证或指定 SSH 协议，否则go mod download会卡在 auth 环节
require 中的版本号为什么有时带 // indirect 标记
// indirect 不代表“不重要”，而是说明该依赖未被当前模块的任何 .go 文件直接 import，仅因其他依赖传递引入。它暴露了真实依赖图中的隐式耦合。
- 常见于测试工具（如
github.com/stretchr/testify）只在*_test.go中使用，但go.mod仍将其列为require——这是正常行为 - 若生产代码里出现大量
// indirect依赖，往往意味着某依赖包把不该导出的实现细节（如内部工具函数）暴露成了公共 API，导致下游被迫拉入冗余模块 -
go mod graph可查清谁引入了某个// indirect包；go list -m all | grep xxx能定位具体路径 - 手动删掉
// indirect行会导致go mod tidy下次自动加回，除非你同时移除所有引用它的上游依赖
replace 和 exclude 的实际使用边界在哪
replace 是调试利器，exclude 是临时止血方案，但两者都绕过了 Go 的版本解析机制，上线前必须清理。
立即学习“go语言免费学习笔记（深入）”；
-
replace适用于：本地开发时打补丁（replace github.com/org/lib => ./local-fix）、跨模块联调（replace example.com/project/user => ../user）、或替换不兼容的第三方 fork -
replace不会改变go.sum校验逻辑——它只是把下载源指向本地路径，校验和仍来自原始模块的 tag，所以替换目录里不能随意改go.mod内容 -
exclude仅用于规避已知 panic 的特定版本（如exclude github.com/badlib v1.2.3），但它不解决根本问题；如果多个依赖都要求这个被排除的版本，MVS 可能选不出合法解，导致go build失败 -
go mod edit -dropreplace和go mod edit -exclude可批量清理，但务必确认 CI 流程中不再需要这些临时指令
go.sum 文件里 checksum 不匹配怎么办
go.sum 不是“锁文件”，而是每个模块版本对应的内容哈希快照。不匹配 ≠ 有问题，但必须人工确认来源是否可信。
- 常见触发场景：依赖库重发同版本 tag（违反 SemVer）、私有模块未启用
GOSUMDB=off、或代理缓存污染 - 先运行
go clean -modcache清空本地模块缓存，再go mod download重拉，看是否仍报错 - 若确认远程模块内容确实变更（如作者修正了严重 bug 并 force-push），可执行
go mod verify检查哪些模块哈希失效，再go mod tidy更新go.sum - 严禁直接编辑
go.sum手动改 checksum——Go 工具链会拒绝加载校验失败的模块，且下次tidy会覆盖你的修改
真正容易被忽略的点在于：模块路径一旦发布就不能随意改，哪怕只是大小写调整或加个下划线，都会让下游 go get 失败。版本控制不是只管“能不能跑”，而是确保“所有人跑的确实是同一份字节”。
