根本原因是go模块路径严格区分大小写，import语句、go.mod中module声明、文件系统目录名及远程仓库url三者必须完全一致（含大小写），否则go build直接报错无法解析包。
go build 报错：cannot find module providing package，但路径明明存在
根本原因是 Go 模块路径严格区分大小写，而 import 语句中的路径与 go.mod 中 module 声明、文件系统目录名、远程仓库 URL 三者不一致。比如你在代码里写了 import "github.com/MyOrg/MyRepo/utils"，但实际仓库是 github.com/myorg/myrepo，或本地目录叫 myrepo，Go 就会彻底拒绝解析——它不尝试纠错，直接报错。
常见触发场景：
- 从 GitHub 复制 URL 时手动改了大小写（如把
github.com/uber-go/zap写成github.com/Uber-Go/Zap） - Windows 文件系统默认不区分大小写，你重命名目录后 Git 没记录变更，
go mod tidy却按原始大小写校验 - 私有 GitLab 仓库路径含大写字母，但
go.mod里声明为小写，或反之
实操建议：
- 用
go list -m all查看当前解析出的所有模块路径，确认是否与 import 语句完全一致（包括大小写） - 检查
go.mod第一行module声明，必须和你所有import的前缀完全匹配，且与远程仓库 URL 一字不差 - 在终端用
ls或dir确认本地目录名大小写，尤其注意 Windows 上可能显示正常但实际存储为小写 - 若已推送到远程，别改本地目录名——改
go.mod和所有import，保持与远程 URL 一致
replace 本地依赖时路径大小写错误导致 go build 失败
replace 指令对路径大小写同样敏感。即使目标目录在文件系统里能打开，只要 replace 行里的路径与实际目录名大小写不符，go build 就会跳过替换、继续走网络拉取，最终因网络不通或权限失败而中断。
例如：
replace github.com/MyOrg/MyLib => ./mylib
但实际目录是 MyLib（首字母大写），Go 就不会生效，仍尝试去 GitHub 找 MyOrg/MyLib。
实操建议：
-
replace右侧路径必须是相对于当前go.mod的**精确大小写路径**，推荐用 shell 补全（Tab 键）避免手误 - 不要用
~/path或环境变量，Go 不展开它们；统一用./subdir或绝对路径（如/home/user/MyLib） - 被
replace的本地目录必须包含有效的go.mod，且其module名也要与replace左侧完全一致（含大小写） - 运行
go mod graph | grep MyLib确认替换是否已生效；若没出现本地路径，说明replace未命中
CI 构建失败：本地能编译，GitHub Actions 却报 checksum mismatch
这是大小写问题最隐蔽的后果。你在 macOS 或 Windows 上开发时，文件系统容忍大小写差异，go mod tidy 能成功生成 go.sum；但 CI 运行在 Linux 上，路径严格区分大小写，校验时发现 import 路径与 go.sum 记录的路径不一致，就拒绝加载。
典型错误信息：
verifying github.com/MyOrg/MyRepo@v0.1.0: checksum mismatch
实操建议：
- CI 中加一步检查：
git status --ignored，确认没有因大小写变更产生的未提交文件（Git 默认不跟踪大小写变更） - 在 CI 脚本开头加
find . -name '*.go' | xargs grep -n 'import.*github.com'，快速扫描所有 import 是否统一风格 - 本地开发完，用 Linux 容器验证：
docker run --rm -v $(pwd):/work -w /work golang:1.21 sh -c "go mod tidy && go build ./..." - 一旦发现大小写不一致，用
git mv重命名目录（如git mv myrepo MyRepo），确保 Git 记录变更
go get 失败后手动改 import 路径反而让问题更糟
遇到 go get 报错，有人会直接修改所有 import 行，试图“匹配”自己本地目录结构。这只会让模块路径进一步偏离事实，后续 go mod tidy 无法收敛，go.sum 校验失效，协作同事拉代码后立刻编译失败。
实操建议：
- 永远不要为了“让本地编译通过”而篡改
import路径——import 路径就是模块身份，不是文件路径别名 - 如果远程模块路径确实有大小写问题（比如公司旧仓库用了大写），唯一合规做法是：在
go.mod用replace映射到正确路径，并联系仓库维护者修正 URL - 用
go mod edit -json查看当前模块声明和所有 replace 规则，确认没有冲突或重复映射 - 删除
go.sum后重新go mod tidy，比手动修 import 更安全；Go 会按go.mod和实际文件结构重建校验值
大小写不是风格问题，是 Go 模块系统的硬性契约。一个字母的差异，就能让整个构建链路在不同环境上断裂。与其事后排查，不如在 go mod init 时就盯紧远程 URL，用 git clone 的原始路径作为唯一权威来源。
