Go不支持Git子模块自动解析，需手动初始化子模块并用replace绑定本地路径，否则导入失败；CI需配置递归拉取子模块，否则构建静默失败。
Go 本身不支持 Git 子模块的自动解析或构建集成——go build、go mod tidy 完全无视 .gitmodules 文件，也不会递归拉取子模块内容。你必须手动确保子模块已检出且路径正确，否则 Go 工具链会按普通目录（甚至空目录）处理，导致包导入失败或编译报错。
Git 子模块未初始化导致 import 路径无法解析
常见现象：项目中 import 了类似 "github.com/yourorg/project/submodule" 的路径，但 go build 报 no required module provides package 或直接提示找不到包；而该路径实际对应的是本地子模块目录，不是远程 Go 模块。
- Git 子模块默认不会随
git clone自动检出，需显式运行git submodule init && git submodule update - 若子模块路径在 Go 代码中被当作模块路径引用（如
import "example.com/repo/utils"），但该子模块未发布到 Go Module Proxy，也未在go.mod中用replace显式指向本地路径，则go mod tidy会失败 - 推荐做法：子模块只用于存放非 Go 模块资源（如脚本、配置、C 库头文件），或明确将其作为独立 Go 模块管理，并通过
replace绑定本地路径
用 replace 将子模块绑定为本地 Go 模块
当子模块本身是一个合法 Go 模块（含 go.mod），且你想在父项目中直接引用其代码（而非仅作静态资源），就必须在父项目的 go.mod 中添加 replace 指令，否则 Go 不会识别子目录为有效模块源。
例如子模块路径为 ./internal/tools，其 go.mod 声明模块名为 example.com/tools：
立即学习“go语言免费学习笔记（深入）”；
replace example.com/tools => ./internal/tools
-
replace必须写在父项目go.mod的require块之后、module声明之后 - 执行
go mod tidy后，Go 才会把该import解析为本地路径，而非尝试从 proxy 下载 - 若子模块尚未有版本标签，
go mod tidy可能报错 “missing go.sum entry”；此时先运行go mod vendor或手动补全go.sum（不推荐），更稳妥的是在子模块中打一个临时 tag（如v0.0.0-20240101000000-abcdef123456）并更新replace行为指向该 commit
CI/CD 环境中子模块未自动同步
GitHub Actions、GitLab CI 等默认只执行浅克隆（--depth=1），且跳过子模块初始化，导致构建时子模块目录为空，Go 编译失败。
- GitHub Actions 示例（关键步骤）：
steps:
- uses: actions/checkout@v4
with:
submodules: 'recursive' - GitLab CI 需显式加命令：
git submodule sync --recursive && git submodule update --init --recursive - 若子模块使用 SSH 地址（如
git@github.com:...），CI 环境需配置 SSH key 或改用 HTTPS + token 方式，否则git submodule update会因鉴权失败中断
真正麻烦的不是“怎么加子模块”，而是子模块路径是否被 Go 视为有效模块源、以及 CI 是否真把它拉下来了——这两点漏掉任意一个，都会让本地能跑通的代码在构建机上静默失败。
