go mod init 后导入路径必须匹配 module 名，如 go mod init example.com/myapp，则所有子包导入路径须以 example.com/myapp 为前缀，否则编译失败。
go mod init 后导入路径必须匹配 module 名
你执行 go mod init example.com/myapp，生成的 go.mod 第一行就是模块根路径。所有本地子包的导入路径都必须以它为前缀，比如 utils 目录要写成 example.com/myapp/utils，而不是 ./utils 或 utils。
常见错误现象：build command-line-arguments: cannot load utils: cannot find module providing package utils —— 这说明 Go 没找到对应模块路径下的包，根本不是“找不到文件”，而是“没按模块路径找”。
- 模块名建议用真实域名或组织路径（如
github.com/yourname/project），避免纯名称（如myapp）导致跨项目冲突 - 目录结构必须与导入路径严格一致：若导入
example.com/myapp/internal/log，则必须存在internal/log/子目录 -
package声明名（如package log）可以和目录名不同，但不推荐；Go 工具链和 IDE 依赖目录名推导包名，不一致易引发 lint 报错或跳转失效
为什么不能用 ./ 或 ../ 导入本地包
Go 编译器在解析 import 语句时，只认逻辑路径（import path），不认文件系统路径。写 "./utils" 会被直接拒绝，报错类似：local import "./utils" in non-local package。
这个限制不是 bug，是设计强制项：确保任意环境构建时，包引用都能被唯一、稳定地解析。相对路径会随当前工作目录变化而失效，破坏可复现性。
-
go run main.go单文件运行时看似能绕过，是因为它临时启用“单文件模式”，但该行为不参与模块解析，也不生成go.mod，不可用于正式构建 - 即使项目在
$GOPATH/src下，只要存在go.mod，Go 就走模块模式，GOPATH路径规则自动失效 - 试图用
replace指向相对路径（如replace example.com/myapp/utils => ./utils）是无效的，replace右侧必须是绝对路径或 Git URL
多个本地包共存时的目录组织要点
本地包不是靠物理位置“就近”就能导入，而是靠模块路径拼接。一个典型结构应是：
myproject/
├── go.mod # module github.com/user/myproject
├── main.go # import "github.com/user/myproject/router"
├── router/
│ └── server.go # package router
├── internal/
│ └── auth/
│ └── token.go # package auth（internal 下包不可被外部模块导入）
└── pkg/
└── utils/
└── str.go # package utils
关键点在于：所有子目录的导入路径都从 go.mod 的 module 行开始拼接。
-
internal/目录下包只能被同一模块内代码导入，Go 编译器会静态检查，防止意外泄露 - 不要把多个独立模块放在同一仓库根下（如
lib1/和lib2/各有go.mod），否则主项目无法直接 import，必须用replace或统一为单模块 - 如果真需拆多模块，每个模块应有独立仓库和
go.mod，主项目通过go get github.com/user/lib1@commit引入
go mod tidy 不会自动修复错误的 import 路径
go mod tidy 只管理第三方依赖的增删和版本对齐，它完全不碰你代码里的 import 语句。写错路径（比如漏掉模块前缀）后执行 tidy，它只会静默忽略，不会报错，也不会帮你补全。
真正有效的验证方式只有两个：go build 或 go list -f '{{.Name}}' github.com/user/myproject/utils（检查包是否可解析）。
- IDE（如 VS Code + Go extension）的自动导入功能，往往默认插的是短路径（如
utils），你需要手动改成完整模块路径 - 重构重命名模块时，必须同步改三处：
go.mod第一行、所有import语句、CI/CD 中的构建路径假设（比如 Dockerfile COPY 路径） - CI 环境中若出现 “cannot find module” 错误，90% 是因为
go mod init没在项目根目录执行，或go.mod被 gitignore 忽略了
模块路径不是配置项，是契约。写错一次，整个依赖解析链条就断了——它不像函数调用错了还能 debug，而是连编译器第一步都过不去。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
