根本原因是项目未初始化模块，需在根目录执行go mod init module-name且module-name须与import路径前缀一致；生成go.mod后运行go mod tidy才能解析并下载依赖。
go build 报错 “cannot find module” 是因为没生成 go.mod
Go 不会自动为项目创建模块元数据，go build 遇到未声明的第三方 import 时，直接报 cannot find module 或 no required module provides package，而不是尝试下载——它根本不知道该去哪下、下哪个版本。
关键动作只有一条：go mod init <module-name></module-name>。这个命令必须在项目根目录执行，且 module-name 要和代码中实际使用的 import 路径前缀一致（比如 import "github.com/xxx/lib"，就该用 go mod init github.com/xxx/lib）。
- 如果只是临时测试，
module-name可以随便起（如go mod init tmp），但后续推送到仓库或协作时必须修正 -
go.mod生成后，再运行go build或go run main.go才会触发依赖解析和自动下载 - 若已有
go.mod但内容为空或缺失require块，说明初始化失败或被误删，应重新执行go mod init或补上go mod tidy
go mod tidy 后仍报 missing dependency，可能是 import 未被识别
go mod tidy 只扫描当前模块里所有 .go 文件中的 import 语句，并据此更新 go.mod。如果某个包被 import 了但没被实际使用（比如只写了 import "github.com/sirupsen/logrus" 却没调用任何函数），Go 工具链可能跳过它——尤其当该 import 被包裹在条件编译块（// +build ignore）或注释掉的代码里时。
- 检查是否漏写了
logrus.WithField(...)这类实际调用，空 import 不足以触发依赖添加 - 确认文件编码是 UTF-8 无 BOM，BOM 会导致 Go 解析器跳过首行 import
- 留意
_空导入：像import _ "net/http/pprof"是有效的，会被go mod tidy拉入，但普通注释掉的 import 不算 - 如果用了
//go:generate或其他指令，确保它们不干扰 import 解析路径
IDE 显示红色波浪线但 go build 成功，多半是缓存没刷新
Goland 或 VS Code 的 Go 插件依赖本地模块缓存（$GOPATH/pkg/mod）和 go list -m all 的结果。即使 go build 成功，IDE 也可能因缓存陈旧、多版本共存或 replace 规则未生效而标红。
- 先运行
go list -m all | grep your-package，确认该包是否真出现在解析列表里 - 执行
go clean -modcache清空全部模块缓存（注意：会删掉所有本地下载的模块，下次构建需重下） - 在 Goland 中右键项目 →
Reload project，或点击编辑器顶部的Sync dependencies按钮 - 检查
go.mod里是否有replace指向本地路径但路径已移动或不存在——这种错误 IDE 往往比命令行更早暴露
私有仓库或子模块报 unknown revision，得配 GO_PRIVATE 或加 replace
Go 默认把所有域名当作公开仓库处理，走 GOPROXY。遇到 unknown revision 或 module not found，往往不是网络问题，而是 Go 根本没尝试去 Git 服务器拉代码。
- 对私有域名（如
git.internal.company.com），必须设置GO_PRIVATE=git.internal.company.com，否则 Go 会跳过直连 - 对同一仓库下的子模块（如
github.com/user/repo/sub），确保子模块根目录有独立的go.mod，否则主模块无法识别其版本 - 开发阶段调试本地依赖时，用
replace github.com/user/lib => ./local/lib，但上线前务必删掉——CI 环境通常没有./local/lib路径 -
replace和require共存时，replace永远优先；可用go list -m -f '{{.Replace}}' github.com/user/lib查看是否被覆盖
go.mod 文件驱动，且只响应“被 import 并被使用”的包。一个没调用的 import、一个拼错的模块名、一次忘记 go mod init，都会让整个依赖链静默失效。
