根本原因是Go模块感知与GO111MODULE模式、当前目录、go.mod位置及GOROOT/GOPATH状态未对齐，尤其在GOPATH向module迁移时，残留结构或go.sum校验失败会加剧路径敏感性。
为什么 import 路径一动，go build 就报 import cycle 或 cannot find package
根本原因不是路径写错了，而是 Go 的模块感知和工作区模式（GO111MODULE）与当前目录、go.mod 位置、GOROOT/GOPATH 状态三者没对齐。尤其当项目从 GOPATH 模式迁移到 module 模式时，残留的 src/ 目录结构或未清理的 go.sum 会放大路径敏感性。
实操建议：
- 确认当前目录下存在
go.mod，且module声明值与你代码中所有import的前缀完全一致（比如module github.com/user/proj，那所有import "github.com/user/proj/util"才合法） - 执行
go env -w GO111MODULE=on强制启用 module 模式，避免意外退回到 GOPATH 模式 - 删掉整个
go.sum并运行go mod tidy—— 不要手动编辑它，校验失败时它比go.mod更容易卡住编译 - 检查是否有
replace指向本地路径（如replace example.com/foo => ./foo），这类替换必须确保./foo下也有有效的go.mod，否则导入解析直接失败
go mod edit -replace 替换本地包后仍提示找不到
常见于想快速调试子模块时用 -replace 指向本地文件夹，但 Go 不会自动把该文件夹当作 module 处理，除非它自己有 go.mod。
实操建议：
- 进入你要替换的本地目录（如
./pkg/db），运行go mod init example.com/pkg/db（模块名可任意，但需唯一） - 回到主项目根目录，再执行
go mod edit -replace example.com/pkg/db=./pkg/db - 运行
go mod tidy，观察是否在go.mod中生成了对应replace行；若没有，说明路径不匹配或模块名拼错 - 不要用相对路径向上越级太多（如
../other-proj），Go 对跨 project 的 replace 支持脆弱，优先考虑用git+replace指向 commit hash
IDE（VS Code / Goland）里能跳转，但 go build 报错
这是最典型的「环境不一致」：IDE 可能读取了 go.env 或缓存了旧的 GOPATH，而终端里的 go build 是干净的 module 模式。跳转成功只说明符号索引没问题，并不代表 import 路径被 Go 工具链认可。
实操建议：
- 在终端执行
go list -m，确认当前模块名是否与go.mod一致；如果输出是command-line-arguments，说明没在 module 根目录下运行命令 - 在 VS Code 中检查右下角 Go 状态栏，点击它 → “Pick Go Environment”，确保选中的是你项目所在 workspace 的
go（而非系统全局或 GOPATH 下的） - 关闭 IDE，删除项目下的
.vscode/和go.work（如果存在），重新打开并等待 Go 插件完成初始化 - 禁用 Goland 的 “Use GOPATH that contains checked out sources” 选项（Settings → Go → GOPATH）
多 module 项目中 import 路径为何总差一级
比如主模块是 github.com/user/app，子模块是 github.com/user/app/internal/log，但你在 app/cmd/main.go 里写 import "github.com/user/app/internal/log" 却报错——问题往往出在子模块没被主模块“声明依赖”，或者子模块的 go.mod 名字和 import 路径不一致。
实操建议：
- 子模块的
go.mod第一行必须是module github.com/user/app/internal/log，不能简写成module log或module internal/log - 主模块运行
go mod edit -require=github.com/user/app/internal/log@v0.0.0（版本号随意，只要格式合法），再go mod tidy - 避免在子模块里用
replace指向更上层目录（如replace github.com/user/app => ../..），这会破坏 module 边界，导致go build无法确定哪个go.mod是权威的 - 如果只是内部组织需要，优先用目录隔离（
app/internal/log）而非独立 module，减少路径层级干扰
go.sum 就清除了状态，其实 go mod download 缓存、GOROOT/src 里的标准库 alias、甚至 shell 的 CWD 都可能悄悄参与 import 解析。 
