构建 Go 项目时，package 找不到的报错往往不像语法错误那样直接指向某一行代码，而是暴露了项目结构、模块缓存或环境变量之间的不匹配。Go 语言对源码的组织有明确约定：import 路径既不是随意起的别名，也不等同于文件系统里的任意相对路径，它必须从模块声明或 GOPATH 的 src 目录开始映射。遇到 cannot find package、no required module provides package 或 package xxx is not in GOROOT 这类信息，优先排查的不是代码逻辑，而是包解析链路。
很多构建错误并不是代码写错，而是当前目录、go.mod 声明、环境变量三者没有统一。排查时先不要急着改动业务代码，而是确认 go 命令到底在按照哪套规则查找包。理解了这一点，后续调整目录结构或环境配置才有明确方向。
先弄清Go的包查找逻辑与报错来源
Go 的包解析机制经历过一次重要切换。早期语言依赖 GOPATH 作为唯一工作区，所有源码必须放在 GOPATH/src 下面，import 路径从 src 开始逐级对应目录。例如 import git.ipipp.com/util/stringx 对应目录 $GOPATH/src/git.ipipp.com/util/stringx。后来引入 Go Modules 后，项目可以脱离 GOPATH 目录，通过 go.mod 里的 module 声明定义模块路径，import 路径从模块路径开始计算。
如果当前目录没有 go.mod 文件，而且 GO111MODULE 环境变量被设为 off，Go 会回退到 GOPATH 模式；此时 import 的包如果不在 GOPATH/src 下，编译器就会报 cannot find package。反过来，如果项目有 go.mod，但 import 使用的是旧 GOPATH 风格路径，也可能出现 no required module provides package。因此报错的第一件事是确认 go env GO111MODULE 和 go env GOMOD 的输出。
go env GO111MODULE go env GOMOD go env GOPATH go env GOROOT
这些输出中，GOROOT 指向标准库安装目录，GOPATH 指向全局工作区，GOMOD 如果显示空说明当前不在模块上下文。掌握这几个路径关系后，更容易判断 import 路径到底应该怎么写，而不是盲目修改代码。特别是 GOROOT 内的包属于标准库，import 路径不会带域名；而 GOPATH/src 或模块路径下的包则会带完整前缀。
例如标准库中可以使用 encoding/json，但项目内部包不能写作 json，即使目录名也叫 json。包查找只认 import 路径前缀，不认目录名的绝对位置。
优化项目结构：把import路径和目录严格对齐
Go Modules 项目最常见的找不到包场景，是目录名与 import 路径不一致，或者模块根目录嵌套错误。假设模块根目录是 app，go.mod 里声明 module ipipp.com/backend/app，那么包 internal/config 的导入路径必须写 ipipp.com/backend/app/internal/config。即使是项目内部包也不能写相对路径 ../config，也不能只写 internal/config。
推荐结构如下：
app/
go.mod
cmd/
server/
main.go
internal/
config/
config.go
store/
db.go
pkg/
logger/
logger.go
在这个结构中，如果 main.go 想导入内部配置包，import 应写 ipipp.com/backend/app/internal/config。只要有一个目录层级拼写错误，go build 就会提示没有这个包。另一个容易踩坑的地方是嵌套 go.mod：当子目录里存在另一个 go.mod 时，该子目录会被当成独立模块，父模块不能直接导入它的内部包，除非使用 replace 或将其作为独立模块发布。若不是刻意拆多模块，删除子目录里的 go.mod 通常能解决。
写完 go.mod 后应执行 go mod tidy，它会根据源码中的 import 自动补全 require，并清理不再使用的依赖。依赖解析完成后，go.sum 也会同步更新。不少包找不到问题在 go mod tidy 执行后就会暴露真正来源，比如 import 路径写错、依赖版本冲突或网络拉取失败。
cd /path/to/app go mod init ipipp.com/backend/app go mod tidy go build ./...
还需要注意，包名与目录名不一定要一致，但 import 路径最后一个元素是目录名，不是 package 名。比如目录 config 内的文件 package 声明为 cfg，导入时仍然写 config。很多开发者容易在重构目录时改了 package 名，却忘了 import 路径仍然以目录为准。
环境配置排查：GOPROXY、GOPRIVATE和模块缓存
即使项目结构和 import 都正确，依赖包仍可能因为网络访问不到而构建失败。go 命令默认从 proxy.golang.org 拉取公共模块，但某些网络环境下该地址不可达，或私有仓库无法直接下载。此时需要配置 GOPROXY 和 GOPRIVATE。
GOPROXY 支持多个源，用逗号分隔，direct 表示跳过代理直接访问版本控制系统。对于公共模块可以配置速度更快的镜像源；对于公司内部私有模块，应通过 GOPRIVATE 指定域名前缀，避免走公共代理和校验数据库。配置命令如下：
go env -w GOPROXY=https://proxy.golang.org,direct go env -w GOPRIVATE=git.ipipp.com,*.corp.ipipp.com go env -w GONOSUMDB=git.ipipp.com,*.corp.ipipp.com
如果依赖已经下载过，但构建时仍然报包找不到，可能是模块缓存不完整。可以清空缓存后重新拉取：
go clean -modcache go mod download
go clean -modcache 会删除 $GOPATH/pkg/mod 下的所有模块缓存，比较彻底，但会让下次构建重新下载全部依赖，适合网络稳定时执行。若只是个别包损坏，可先尝试 go mod download github.com/some/package。执行 go env GOMODCACHE 可以查看当前模块缓存目录。如果 CI 环境和本地机器路径不一致，也要确认模块缓存没有被意外清空。
用调试命令快速定位包加载失败点
当报错信息不够明确时，go list 和 go mod why 是有效的定位工具。go list -m all 列出当前模块和依赖的完整模块图；go mod why -m 模块路径 可以解释某个模块为什么被依赖。go build -x 则会打印每一步实际执行的命令与搜索路径，适合确认 go 正在尝试从哪里读取包。
go list -m all go mod why -m git.ipipp.com/backend/common go build -x ./...
另一个容易被忽略的因素是编辑器或 CI 环境中的 GOFLAGS。部分团队在开发环境设置了 GOFLAGS=-mod=vendor，导致构建强制使用 vendor 目录，而本地没有执行 go mod vendor，于是提示包不存在。如果项目使用 vendor 模式，每次修改 go.mod 后必须重新生成 vendor 目录；否则应在构建时显式使用 -mod=mod，让 go 从模块缓存解析依赖。
go env -w GOFLAGS=-mod=mod go mod vendor go build -mod=vendor ./...
排查包找不到问题时，建议按照固定顺序操作：先确认 GO111MODULE 和 GOMOD，判断处于哪一种模式；再检查 import 路径是否从模块路径开始；接着执行 go mod tidy 观察依赖解析；最后检查 GOPROXY 和 GOPRIVATE 网络配置。这样能避免反复试错，也能让项目结构保持清晰，后续 CI、容器构建和本地开发共享同一套规则。