“module not found”错误主因是import路径与模块路径不匹配、go.mod缺失或损坏、GOPROXY配置不当、本地缓存异常；需依次检查go.mod存在性、import拼写、代理设置及缓存状态。
Go 出现 “module not found” 错误，通常不是 Go 本身找不到模块，而是 go 命令在解析 import 路径时，无法定位到对应模块的根目录或版本信息。核心原因集中在模块路径、go.mod 状态、代理配置和本地缓存这四个层面。
import 路径与模块路径不匹配
Go 模块通过 import 路径（如 "github.com/sirupsen/logrus"）查找模块，该路径必须与模块的 module 声明完全一致。常见问题包括：
- 代码里写了
"logrus"或"github.com/Sirupsen/logrus"（大小写错误或旧路径），但 go.mod 中是github.com/sirupsen/logrus - 项目未初始化模块，却用了带域名的 import 路径（例如在无 go.mod 的项目中直接 import "example.com/mylib"）
- 本地依赖用 replace 替换后，路径未同步更新，导致 import 仍指向原路径但模块已不可达
go.mod 缺失、损坏或未更新
Go 1.11+ 默认启用 module 模式，go.mod 是模块的“身份证”。出错常因：
- 项目根目录没有
go.mod文件（执行go mod init example.com/myapp初始化） -
go.mod存在但没包含实际用到的模块（运行go mod tidy自动补全依赖并清理冗余项） - 手动编辑了
go.mod导致格式错误或 checksum 不匹配（建议避免手改，用go mod edit或命令操作）
GOPROXY 配置不当或网络受限
Go 默认通过代理（如 https://prox）下载公共模块。若无法访问代理，就会报 “module not found”：
y.golang.org
- 国内环境未配置可用代理（推荐设为
export GOPROXY=https://goproxy.cn,direct） - 公司内网禁用了外部代理，又没配
direct回退（digital表示直连私有仓库或本地路径） - 代理返回 404 或超时，但错误被笼统显示为 “not found”（可用
curl -I https://goproxy.cn/github.com/sirupsen/logrus/@v/v1.9.3.info测试）
本地缓存或 vendor 干扰
Go 会缓存下载的模块到 $GOPATH/pkg/mod。异常情况包括：
- 缓存损坏（删除
$GOPATH/pkg/mod/cache/download和cache/vcs可强制重拉） - 启用了
GO111MODULE=off，Go 降级走 GOPATH 模式，忽略 go.mod，导致模块路径失效 - 项目启用了
vendor但未更新（go mod vendor后未同步代码中的 import 路径）
基本上就这些。排查时优先检查 go.mod 是否存在、import 路径是否拼写准确、GOPROXY 是否生效，再看缓存和模式开关。不复杂但容易忽略细节。
