Go模块多目录管理核心是每个可构建单元必须有独立go.mod且位于其逻辑根目录；go run报“cannot find module”因当前目录无go.mod，Go只认当前目录是否存在go.mod来识别模块上下文。
Go 模块的多目录管理，核心就一条：每个独立可构建/发布的单元，必须有自己独立的 go.mod 文件，且该文件必须位于其逻辑根目录下；不存在“全局模块”或“父模块自动管理子目录”的概念。
为什么 go run 在子目录里总报 “cannot find module providing package”
这不是路径写错了，而是你当前工作目录下没有 go.mod，Go 工具链根本没识别出这是一个模块上下文。
- Go 不靠目录嵌套关系推断模块边界，只认
go.mod文件是否存在、是否在当前目录 - 你在
myapp/handlers目录下执行go run *.go，但那里没有go.mod→ 报错 - 正确做法是：回到含
go.mod的根目录（如myapp/）再运行，或确保子目录本身就是一个独立模块（即有自己的go.mod） - IDE（VSCode/GoLand）打开单个
.go文件时，常因未识别模块根目录而提示包找不到——必须用「打开文件夹」方式打开项目根目录
replace 是本地多模块协作的唯一可靠方式
当主项目要引用本地开发中的子模块（比如 myapp/user 和 myapp/order），不能靠相对路径导入，也不能靠 GOPATH，必须显式声明重定向。
- 子模块需先在自己目录下执行
go mod init myapp/user，生成自己的go.mod - 主模块的
go.mod中添加：replace myapp/user => ./user<br>require myapp/user v0.0.0
-
v0.0.0是占位版本号，实际不生效；replace优先级高于远程依赖，Go 会直接读取本地./user目录 - 删掉
replace行后不执行go mod tidy，旧缓存可能让构建继续成功——这是最隐蔽的坑
子包 vs 子模块：命名和导入路径必须严格对应
同一个模块内，子目录名就是包名，但导入路径是模块名 + 子目录路径；跨模块则必须用完整模块名作为前缀。
立即学习“go语言免费学习笔记（深入）”；
- 模块名为
myapp，目录myapp/utils下的包名是utils，导入写法是"myapp/utils" - 若把
utils单独抽成模块（myapp-utils），它的go.mod必须声明module myapp-utils，其他项目导入时写"myapp-utils"，而非"myapp/utils" - 包名可以和目录名不同（如
utils/下写package helpers），但强烈不建议——会破坏工具链对路径的自动解析（gopls、go list等） - 模块名必须全小写、无下划线、无大写字母；否则
go mod download或某些 CI 工具会静默失败
多模块项目最容易被忽略的三个点
不是语法问题，而是工程上下文被误判：
-
go mod tidy必须在每个模块根目录单独执行，根目录运行不会递归处理子模块的go.mod - 清理依赖缓存用
go clean -modcache是全局操作，它不解决模块路径错误——真正要 fix 的是go.mod里的module声明和replace路径 - Git 仓库里如果漏提交某个子模块的
go.mod，CI 构建时会因无法解析模块路径而失败，但本地可能因缓存正常——这个差异极难复现
