报“no required module provides package”错误，本质是依赖不可达，需逐层验证：确认go.mod存在且GO111MODULE=on、检查require是否声明并已拉取、核对import路径与模块定义一致、排查replace/私有库/间接依赖断裂等问题。
报 no required module provides package github.com/xxx，不是包不存在，而是当前模块没声明它、或声明了但没拉下来、或拉了但路径/版本不匹配——得一层层验证依赖链是否真正“可达”。
检查 go.mod 是否存在且被识别
Go 不会自动读取 go.mod 文件，必须满足两个前提：当前目录是模块根目录，且 GO111MODULE=on。常见错觉是“文件在那儿就行”，实际可能：
- 你在子目录执行
go build，而go.mod在父目录 —— 必须 cd 到含go.mod的目录再操作 -
go env GO111MODULE输出off或auto且当前不在$GOPATH/src下 —— 直接运行go env -w GO111MODULE=on - 项目路径含中文、空格或符号（如
my app）—— Go 解析 import 路径时会失败，重命名目录即可
确认包是否已声明并下载
go.mod 里有 require 条目，不等于包就“可用”。Go 构建时只认 go.sum 中记录的校验和 + pkg/mod 缓存里的实际文件。典型断点：
-
go.mod有github.com/cloudwego/hertz v0.12.0，但go.sum没对应行 → 运行go mod tidy补全 - 手动删过
pkg/mod或执行过go clean -modcache→ 重新go mod download或等下次go build自动拉 - 用了
replace但路径写错（如./local/hertz实际不存在）→go list -m all看是否显示indirect或replaced
验证 import 路径与包实际路径是否一致
Go 的 import 路径不是文件系统路径，而是模块定义的“逻辑地址”。例如：
立即学习“go语言免费学习笔记（深入）”；
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
若 go.mod 第一行是 module myapp，那 utils/ 子目录必须用 import "myapp/utils"，不能写 "./utils" 或 "utils"；如果 utils/helper.go 里声明的是 package myutil，那代码中调用时得用 myutil.Func()，和 import 路径无关。
更隐蔽的问题：
- 私有库路径拼错，比如
gitlab.example.com/group/proj少了个/group→ 报错提示的包名和你写的 import 完全一致，但 Go 找不到对应模块 - 包被重命名过（如从
v1升级到v2），但 import 还是github.com/xxx/pkg，而新版本要求github.com/xxx/pkg/v2→ 查 GitHub Release 页确认导入路径变更 - 用了
go:embed或//go:generate，生成的代码里悄悄 import 了本不该引入的包 → 检查embed.FS引用的文件或gen.go输出内容
定位间接依赖断裂点
有时错误包不是你直接 import 的，而是某个依赖的依赖“掉链子”。比如 A → B → C，C 包不可达，但你的代码只写了 import "A"。这时候：
- 运行
go list -deps -f '{{.ImportPath}}' . | grep 'github.com/xxx'，看该包是否出现在依赖树里 - 用
go mod graph | grep 'github.com/xxx'查谁在引用它，再顺藤摸瓜看上游模块是否声明了正确版本 - 若发现某依赖标记为
indirect且无版本号（如github.com/xxx v0.0.0-00010101000000-000000000000），说明 Go 没法推导出合理版本 → 手动go get github.com/xxx@latest或指定 tag
最易被忽略的是：某些包（尤其是内部工具类）只在 _test.go 文件里被 import，而测试文件参与构建期依赖分析 —— 删除或注释掉测试中的可疑 import，常能绕过“不可达”报错，再针对性补依赖。
