Go本地包导入必须使用“module名+子路径”格式，如module myapp则需import "myapp/utils"；路径须严格匹配目录结构与go.mod声明，且go mod init须在项目根目录执行。
import 路径必须匹配 go.mod 中的 module 名
Go 1.11+ 启用模块模式后，import 不再认文件系统相对路径（如 "./utils" 或 "utils"），只认「模块名 + 子路径」。比如 go.mod 第一行是 module myapp，而 utils/helper.go 在项目根目录下，那合法写法只能是 import "myapp/utils"。
常见错误现象：main.go:5:2: cannot find package "utils" 或 cannot find package "myapp/utils" —— 后者说明路径写对了但模块名/结构不匹配。
-
utils/helper.go文件顶部必须是package utils（包名可任意，但 import 时用的是路径，不是包名） - 不能把
go.mod里的module改成utils来“凑” import；应该让 import 路径去匹配module声明 - 如果项目嵌套多层（如
myapp/internal/utils），import 路径就得是"myapp/internal/utils"，不能省略internal
go mod init 必须在正确目录执行
执行 go mod init myapp 的目录，必须是包含 main.go 或首个 Go 源文件的项目根目录，且该目录不能位于 $GOPATH/src 下（否则 GO111MODULE=auto 会退化为 GOPATH 模式）。
容易踩的坑：go mod init 在子目录运行，或父目录已有另一个 go.mod，会导致当前代码被识别为子模块而非主模块，import 时路径失效。
立即学习“go语言免费学习笔记（深入）”；
- 运行
go env GO111MODULE，确认输出是on（不是auto或off） - 执行
go list -m，应输出myapp；若报错或输出空，说明不在有效模块根目录 - 如果项目原在
$GOPATH/src/myapp，建议整体移出，放到~/projects/myapp这类任意路径下重新初始化
本地多模块项目要用 replace 显式声明
当主项目依赖另一个本地模块（比如 myapp 要用 mylib），而 mylib 有独立 go.mod 时，仅靠 import 路径不够，必须在主项目的 go.mod 中加 replace 指令。
示例：主项目 go.mod 中需包含：
require mylib v0.0.0 replace mylib => ../mylib
注意：replace 左侧的 mylib 必须和 mylib/go.mod 中的 module 名完全一致；右侧路径是相对于主项目 go.mod 的相对路径。
- 运行
go mod tidy后，replace行才会生效；不运行它，go build仍会尝试从远程拉取mylib -
replace是临时调试手段，上线前应移除，改用真实版本号发布 - 若
../mylib目录下没有go.mod，go mod tidy会报错，此时需先在mylib目录执行go mod init mylib
IDE 缓存没识别模块根目录
VS Code 或 GoLand 提示找不到本地包，但命令行 go build 正常，基本是 IDE 没把含 go.mod 的目录当 workspace root。
关键点：gopls（Go 语言服务器）依赖打开方式判断模块上下文，不是靠文件内容自动推导。
- 在 VS Code 中，必须用「File → Open Folder…」选中
myapp/（含go.mod的目录），而不是它的父目录 - 按
Ctrl+Shift+P输入Go: Restart Language Server强制刷新索引 - 检查设置里
go.gopath是否被手动填写——现代项目应留空，否则 gopls 可能降级到 GOPATH 模式 - 如果项目有多个
go.mod（如 monorepo），确保编辑的文件处于正确模块的目录树内，否则 import 路径可能被解析错
go.mod 声明、import 路径、IDE 打开方式这四者之间有一处没对齐。只要任一环节偏离，就会触发 “cannot find package” —— 它不告诉你具体哪一环断了，只甩一个模糊错误。 
