Go 项目里 git submodule 的路径必须和 import 路径严格一致
Go 不会自动识别或重映射子模块目录，go build 和 go mod tidy 完全依赖 import 路径与磁盘路径的逐字匹配。如果你把子模块克隆到 ./libs/myutil，但代码里写的是 import "github.com/yourorg/myutil"，那 Go 就直接报错 no required module provides package。
- 子模块初始化后，立刻检查
git submodule status是否干净，避免残留未提交的修改干扰路径解析 - 子模块根目录下必须有
go.mod（哪怕只是空模块），否则 Go 认为它不是有效模块，不会参与依赖解析 - 推荐用
git submodule add -b main https://github.com/yourorg/myutil ./myutil，把子模块挂载到和 import 路径末段一致的本地路径（比如github.com/yourorg/myutil→./myutil）
go mod edit -replace 是临时绕过子模块路径不匹配的最快方式
当子模块路径和 import 不一致、又不能马上改仓库结构时，-replace 是最直接的补救手段。它本质是让 Go 工具链在解析依赖时“劫持”某个模块路径，指向本地目录。
- 执行前先确保子模块已检出且
go.mod存在：git submodule update --init --recursive - 假设你想把
github.com/yourorg/myutil指向本地./submodules/myutil，运行：go mod edit -replace github.com/yourorg/myutil=./submodules/myutil - 注意：这个操作会写入
go.mod，CI 环境若没同步子模块内容，go build会失败 —— 所以 CI 脚本里必须包含git submodule sync && git submodule update --init
子模块更新后必须手动 go mod tidy，否则依赖树不会刷新
Git 子模块更新只改变 .gitmodules 和工作区文件，Go 的模块缓存和 go.sum 完全无感。常见现象是：子模块代码已更新，但 go test 仍跑旧逻辑，或者 go list -m all | grep myutil 显示旧 commit hash。
- 每次
git submodule update --remote或切了子模块分支后，回到主项目根目录执行：go mod tidy - 如果子模块本身改了
go.mod（比如加了新依赖），主项目也得重新go mod tidy，否则新依赖不会进主项目的go.sum - 别依赖 IDE 自动触发 tidy —— VS Code 的 Go 插件有时会跳过子模块变更，命令行执行最可靠
CI 环境里 git clone --recursive 不够，还得处理嵌套子模块和权限
很多 CI 流水线只做浅克隆或忽略子模块递归，导致 go build 报 cannot find module providing package。更隐蔽的问题是私有子模块（如 GitHub Enterprise）在 CI 中因 SSH 密钥缺失而拉取失败，但错误日志只显示 “permission denied”，不提 git。
立即学习“go语言免费学习笔记（深入）”；
- CI 脚本第一行建议：
git clone --recursive --shallow-exclude=$(git rev-parse HEAD) https://... && cd $REPO_NAME，避免过度拉取历史 - 私有子模块必须配置 Git 凭据助手，例如 GitHub Actions 中加一步：
git config --global url."https://${{ secrets.GITHUB_TOKEN }}@github.com/".insteadOf "https://github.com/" - 如果子模块里还有子模块（嵌套），普通
--recursive可能不够，改用：git submodule update --init --recursive --depth=1
go.mod；最容易被忽略的，是子模块更新后忘记 go mod tidy，以及 CI 里没处理好嵌套子模块的深度拉取。 
