go mod init 必须在项目根目录执行，模块名应为完整路径如 github.com/yourorg/authsvc；go get 需指定语义版本如 @v2.1.0；grpc 中间件须按子路径导入如 /v2/interceptors/logging；go.sum 校验失败应优先直连下载而非删文件。
go mod init 必须在项目根目录执行，否则依赖路径错乱
很多开发者在子目录下运行 go mod init，结果导致模块名与实际导入路径不一致，后续 import 语句报错或中间件无法被正确解析。Go Modules 的模块名不是目录名，而是你在 go mod init 后指定的路径（如 github.com/yourorg/authsvc），它会成为所有相对导入的基准。
- 错误做法：在
cmd/server/下执行go mod init server→ 模块名变成server，但代码里写import "github.com/yourorg/authsvc/middleware"就会找不到 - 正确做法：cd 到项目最外层目录（含
main.go或顶层go文件），再运行go mod init github.com/yourorg/authsvc - 验证方式：执行
go list -m，输出应为你的完整模块路径，而非server或main这类短名
go get 不要加 @latest，中间件版本必须显式锁定
gRPC 中间件（如 go-grpc-middleware）各子模块（interceptors/logging、interceptors/auth）常独立发布小版本，@latest 容易拉到不兼容的变更——比如 logging.UnaryServerInterceptor 参数签名突然改了，编译直接失败。
- 安全做法：用具体语义版本，例如
go get github.com/grpc-ecosystem/go-grpc-middleware/v2@v2.1.0 - 避免混用 v1/v2：该库 v2 路径含
/v2，若漏掉会导致 go.mod 写入go-grpc-middleware v1.x，而代码 import 的却是go-grpc-middleware/v2/interceptors/logging，触发 “import path not found” 错误 - 检查依赖树：运行
go mod graph | grep grpc-middleware，确认只存在一个主版本号，且无冲突分支
中间件模块需按功能分包导入，不能全量引入
go-grpc-middleware 的设计是“按需加载”，但新手常写 import "github.com/grpc-ecosystem/go-grpc-middleware"，这包本身是空的，没有导出任何拦截器；真正可用的是子路径下的具体实现。
- 正确导入示例：
import "github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/logging"、import "github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/auth" - 注意路径拼写：v2 版本必须带
/v2/，v1 版本路径不含/v2/，且 v1 已归档不再维护 - go.mod 会自动记录子路径依赖，但仅当对应
import语句真实存在时才生效；删掉某行 import 后务必运行go mod tidy，否则残留的 require 条目可能引发构建干扰
go.sum 校验失败时别盲目删文件，先查代理和网络环境
执行 go mod tidy 或 go build 时出现类似 verifying github.com/grpc-ecosystem/go-grpc-middleware/v2@v2.1.0: checksum mismatch，大概率不是本地文件损坏，而是 GOPROXY 缓存了旧哈希或中间件作者重推了 tag。
- 优先尝试：临时关闭代理，用
GOPROXY=direct go mod download强制直连官方源重新下载 - 确认 tag 是否真实存在：访问
https://pkg.go.dev/github.com/grpc-ecosystem/go-grpc-middleware/v2@v2.1.0，看页面是否显示该版本文档 - 慎用
go mod verify：它只校验本地缓存，不解决源头问题；真正要修复的是go.sum中那行哈希值，应由go mod download自动更新
v2 就全盘失效。每次加新中间件前，花三十秒看一眼 pkg.go.dev 上该库的最新导入路径和版本声明，比事后 debug 两小时更省时间。
