根本原因是module名与import路径不一致，必须确保go.mod首行module声明与所有import前缀完全匹配，且GO111MODULE=on、replace路径合法、无相对路径import。
go.mod 中 module 名与实际路径不一致导致报错
模块名必须和代码仓库地址对齐，否则 go build 或 go mod tidy 会拒绝解析依赖，典型错误如：no required module provides package github.com/xxx/yyy，哪怕包物理存在也无效。
- 检查
go.mod第一行：module github.com/user/repo—— 这就是你的“模块名”，所有import路径必须以此为前缀 - 若项目托管在
gitlab.example.com/group/project，但go.mod写成module github.com/user/project，Go 工具链根本不会尝试从 GitLab 拉取，直接报错 - 本地开发未发布时，仍需按未来真实 URL 设定模块名（如
module gitlab.example.com/group/project），不需要真有该域名或仓库，go build只认路径字符串匹配 - 改完
go.mod后必须手动修正所有import语句，go mod tidy不会帮你重写导入路径
使用 ./ 相对路径 import 触发 inconsistent definition 错误
import "./internal/handler" 看似能编译，实则违反 Go 模块设计前提——“导入路径 = 模块路径”，CI、IDE 跳转、多目录构建全会出问题。
- 错误现象包括：
go: inconsistent definition of package xxx、cannot find module providing package ./xxx、go run .在子目录下失败 - 正确做法：假设
go.mod是module github.com/myorg/app，那么./internal/handler应改为import "github.com/myorg/app/internal/handler" - VS Code + gopls 依赖模块路径做符号跳转，相对路径会让所有跳转失效
- 批量修复可用：
gofmt -r 'import "./(.*?)" -> import "github.com/myorg/app/$1"' -w .（需替换为你的真实模块名）
replace 指向 ./ 本地路径被拒绝
replace github.com/mylib => ./local/mylib 会直接报 invalid replace directive，因为 Go 要求 replace 右侧必须是可识别的模块根目录，不是任意文件夹。
Alibabacloud Sdk Client Initialization For Golang
下载
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
- 合法调试写法只有两种：
replace github.com/mylib => /abs/path/to/mylib（绝对路径，仅限单机）或replace github.com/mylib => ../mylib（前提是../mylib是含go.mod的 Git 仓库，且其module声明与左侧完全一致） - 用
go list -m all验证是否生效：输出中对应模块路径应显示为 replace 指向的本地路径 - 上线前务必清理：
go mod edit -dropreplace=github.com/mylib，否则 CI 构建会因找不到本地路径失败 - 不要在
go.mod里硬写require版本再配replace—— replace 永远优先，require行只是文档作用
GO111MODULE=auto 导致模块不识别
即使项目根目录有 go.mod，若环境变量是 auto 或 off，Go 仍可能 fallback 到 GOPATH 模式，报错 no required module provides package。
立即学习“go语言免费学习笔记（深入）”；
- 执行
go env -w GO111MODULE=on全局启用，这是最稳妥做法；auto模式依赖当前路径判断，比如在/tmp/myapp下初始化，它可能直接拒绝识别为模块 -
GO111MODULE=off会彻底禁用模块功能，go mod命令全部失效，go get不写go.mod - 验证方式：
go env GO111MODULE必须输出on；再运行go mod graph | head -n3，有输出说明模块已激活 - CI 环境尤其要注意，默认镜像常保留旧配置，必须显式设置，不能依赖“应该默认开启”
