答案是大小写不一致导致模块路径与声明路径字面量不匹配：Go校验时严格比对require路径和模块go.mod首行module声明，而Windows/macOS文件系统大小写不敏感会掩盖该问题，直到CI或他人构建时爆发。
为什么 go mod tidy 会报 “module declares its path as … but was required as …”
Windows 或 macOS 上执行 go mod tidy 时，常见这类错误：模块 A 声明自己是 github.com/MyOrg/MyRepo，但你的 go.mod 里写的是 github.com/myorg/myrepo（仅大小写不同）。Go 工具链在这些文件系统上能成功解析路径，但校验时严格比对模块声明路径——大小写必须完全一致。
根本原因不是 Go 本身不区分大小写，而是：go mod 在校验时强制要求导入路径与模块定义路径字面量一致；而 Windows/macOS 的底层文件系统（NTFS/HFS+）默认大小写不敏感，导致本地 clone 和缓存路径可能“意外匹配”，掩盖问题直到 CI（Linux）或他人拉取时爆发。
- CI 构建失败最常见场景：本地开发用
go get github.com/myorg/myrepo，实际模块go.mod里写的是github.com/MyOrg/MyRepo -
go list -m all可能显示两个看似相同的模块路径，但哈希不同——说明 Go 已把它们当不同模块缓存了 - 手动改
go.mod中的路径后，go mod download可能失败，因为 GOPATH 或 GOCACHE 里已有旧路径的 checksum 缓存
如何定位并修正大小写不一致的模块路径
先确认当前项目中哪些模块路径和其真实声明不一致。最直接方式是检查每个依赖的 go.mod 文件第一行：
module github.com/MyOrg/MyRepo
再对比你项目 go.mod 里的 require 行。二者必须逐字符相同（包括大小写、连字符、下划线）。
立即学习“go语言免费学习笔记（深入）”；
- 运行
go list -m -f '{{.Path}} {{.Dir}}' all | grep -i myorg查看所有匹配模块的实际路径和本地缓存位置 - 进入对应缓存目录（如
$GOCACHE/v2/github.com/myorg/myrepo@v1.2.3），打开其中的go.mod，看第一行module声明 - 若发现不一致，删掉该模块整个缓存目录（
rm -rf $GOCACHE/v2/github.com/myorg/myrepo@*），避免旧 checksum 干扰 - 统一使用正确大小写的路径重新
go get：比如真实模块声明是github.com/MyOrg/MyRepo，就执行go get github.com/MyOrg/MyRepo@v1.2.3
CI 和团队协作中防止复发的关键配置
单靠人工检查不可靠。关键是在开发流程中堵住源头：
- 在
.gitattributes中添加*.go linguist-language=Go不够，要加**/go.mod text eol=lf确保换行一致，但更关键的是启用 Git 大小写敏感检查：git config core.ignorecase false（仅限 Linux/macOS 开发机；Windows 上无效，需靠其他手段） - CI 脚本中加一步验证：
go list -m all | awk '{print $1}' | sort -u | while read m; do go mod download "$m"@latest >/dev/null 2>&1 || echo "invalid module path: $m"; done - 用
go mod graph输出依赖图后，grep 检查是否有同一仓库出现多个大小写变体（如同时存在myorg/repo和MyOrg/Repo） - 编辑器插件（如 VS Code 的 Go 插件）开启
"go.useLanguageServer": true后，部分版本会在 import 行悬停提示“module path mismatch”，但不能依赖它
遇到 ambiguous import 错误怎么办
当代码里写了 import "github.com/myorg/myrepo"，但 Go 发现缓存里既有 github.com/myorg/myrepo 又有 github.com/MyOrg/MyRepo 的版本，就会报 ambiguous import: found … in multiple modules。
- 这不是编译错误，而是
go build阶段拒绝歧义——哪怕两个路径指向同一 commit，Go 也不允许 - 先运行
go mod edit -droprequire github.com/myorg/myrepo（替换成你用错的路径） - 再删掉
go.sum中对应行（或整行删后go mod tidy重生成） - 确保所有
import语句和go.mod中require行使用完全一致的大小写形式 - 如果模块作者已修复路径（比如从
myorg迁移到MyOrg），应升级到新版本并清理旧引用；不要试图保留旧路径 alias
真正麻烦的不是改一行路径，而是旧 commit 里散落的 import、文档链接、CI 脚本里的 go get 命令——这些地方大小写不一致，都会让问题反复出现。
