go mod tidy 报 ambiguous import 错误是因模块路径大小写不一致导致，需检查并统一 git、go.mod 和文件系统中的路径大小写，尤其注意 macos/windows 与 linux 文件系统差异。
go mod tidy 报 ambiguous import 错误时，先查大小写是否不一致
Go 模块路径区分大小写，但某些文件系统（如 macOS 默认的 HFS+、Windows NTFS）不区分，导致 git clone 或本地开发时路径大小写被“悄悄修正”，最终 go mod tidy 在 CI 或 Linux 构建机上失败，报错类似 ambiguous import: found github.com/ExampleOrg/pkg and github.com/exampleorg/pkg。
这不是版本冲突，而是 Go 加载器在解析 import 路径时发现两个语义相同但字面不同的模块路径——它无法判断该用哪个，直接拒绝构建。
- 执行
go list -m all | grep -i exampleorg查看是否出现大小写混杂的路径 - 运行
git ls-files | grep -i exampleorg检查本地文件系统是否已存大小写不一致的目录（如exampleorg/和ExampleOrg/并存） - 检查
go.mod中所有require行，确认引用路径与官方发布路径完全一致（比如 GitHub 仓库名是小写的，就绝不能写成ExampleOrg）
修复大小写歧义：从 git 索引层强制统一
仅靠编辑 go.mod 不够。Git 可能已缓存错误大小写的路径，导致即使你改了代码，go mod tidy 仍拉取旧路径或报错。
- 先清理本地残留：
rm -rf $(go env GOPATH)/pkg/mod/cache/download/github.com/exampleorg - 从 Git 索引中移除错误路径：
git rm -r --cached github.com/ExampleOrg/pkg（注意这里用的是错误大小写） - 重新添加正确路径：
git add github.com/exampleorg/pkg（确保全部小写） - 提交并推送，再运行
go mod tidy——此时应不再报ambiguous import
CI 构建失败却本地正常？大概率是文件系统大小写策略差异
macOS 开发者常遇到：本地 go build 成功，但 GitHub Actions 或自建 Linux CI 报 ambiguous import。这是因为 macOS 默认文件系统对大小写不敏感，而 Linux ext4 是严格区分的。
- 不要依赖本地“能跑通”来判断路径合法性；始终以 GitHub 仓库 URL 的实际大小写为准
- 在 CI 中加入前置检查：
go list -m all | awk '{print $1}' | sort -u | grep -E '[A-Z]'，快速扫出含大写字母的可疑路径 - 若项目使用
replace指向本地路径，确保该路径名也与go.mod中require的原始路径大小写完全一致，否则replace不生效
避免未来再踩坑：自动化校验 + 提交钩子
大小写问题极难肉眼发现，尤其当路径嵌套较深（如 github.com/SomeCompany/SomeService）。靠人盯不可靠，得靠工具卡住。
- 在
go.mod上方加注释说明规范：// All module paths must match GitHub case exactly. No PascalCase in import paths. - 用 pre-commit 钩子检查：
go list -m all | awk '{print $1}' | grep '[A-Z]' && echo "ERROR: Uppercase found in module path" && exit 1 || true - 如果团队用私有 Git 服务器，可在服务端 hook 中禁止含大写字母的
go.mod提交
大小写歧义不是“偶尔发生的小问题”，它是 Go 模块加载机制和底层文件系统行为叠加产生的确定性故障点。一旦引入，往往在最意想不到的环节爆发——比如上线前最后一轮 CI。早校验，早拦截，比事后 debug 快十倍。
