根本原因是import路径与磁盘路径逐字不匹配；必须满足子模块有go.mod、路径名与import末段完全一致、主go.mod含对应require三条件，否则go build失败。
go build 报 no required module provides package 是路径不匹配
根本原因不是子模块没拉下来，而是 Go 工具链在 import 路径和磁盘路径之间做逐字比对，差一个字符就失败。比如代码里写 import "github.com/yourorg/myutil"，但子模块实际在 ./libs/myutil，Go 就直接放弃解析。
必须满足三个硬条件才能让子模块“被看见”：
- 子模块目录下存在
go.mod（哪怕内容只有module github.com/yourorg/myutil） - 子模块的本地路径名必须和 import 路径末段完全一致：即
github.com/yourorg/myutil→ 应挂载到./myutil，而不是./submodules/myutil或./libs/myutil - 主项目的
go.mod中必须有对应require github.com/yourorg/myutil v0.0.0-00010101000000-000000000000（版本号可占位），否则go mod tidy不会把它纳入依赖图
git submodule update --init --recursive 后 go build 仍失败
常见于 CI 环境或多人协作场景，表面执行了初始化，实则子模块内部的 go.mod 没生效或未被识别。
排查顺序要严格按这个来：
- 进子模块目录，运行
go list -m—— 若报main module not found，说明它没被识别为模块，删掉该目录下所有.git外的残留文件，重新git submodule deinit -f . && git submodule update --init - 确认子模块根目录的
go.mod第一行是准确的module声明，不能是module myutil或module ./myutil - 回到主项目根目录，运行
go mod tidy—— 这步不可跳过，它会把子模块的 require 行写入主go.mod，并更新go.sum - 检查
go list -m all | grep myutil输出是否带版本哈希；若只显示路径无哈希，说明没真正接入模块系统
想临时调试又不想改子模块结构，用 replace 最快
go mod edit -replace 是唯一能绕过路径强制匹配的手段，但它只解决“找得到”，不解决“语义一致”。
操作前先确保子模块已检出且含有效 go.mod：
- 执行
go mod edit -replace github.com/yourorg/myutil=./myutil（注意路径是相对主项目根目录的） - 立刻运行
go mod tidy，否则 replace 不会写入go.mod - 验证是否生效：
go list -m github.com/yourorg/myutil应输出类似github.com/yourorg/myutil => ./myutil - CI 构建前必须删掉这行 replace 并重新
go mod tidy，否则构建节点找不到./myutil
别用 ../myutil 或绝对路径——go mod edit 不接受，会静默失败。
CI 流水线里 git clone --recursive 仍然构建失败
因为 --recursive 只处理一级子模块，而子模块自身可能还嵌套子模块；更隐蔽的是私有仓库权限问题，错误日志往往只显示 permission denied，根本不提 git。
CI 脚本必须显式补全两步：
-
git submodule sync --recursive—— 同步 .gitmodules 里的 URL 变更（尤其当用了镜像源或企业内网地址时） -
git submodule update --init --recursive—— 强制初始化所有层级，包括嵌套的 - 若子模块是私有 GitHub/GitLab，需提前配置 SSH key 或
GOPRIVATE=git.company.com/*，否则go mod download会跳过它去走 proxy 并失败
最后加一句 go mod verify，能在 go build 前暴露 checksum 不匹配问题——这比等编译报错早得多。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
