go mod init生成的module名必须与import路径严格一致，否则报import not found、checksum mismatch等错误；应在项目根目录用真实托管路径初始化，立即go mod tidy，并避免replace长期滥用。
go mod init 生成的 module 名和实际 import 路径不匹配
这是最常见也最容易被忽略的路径报错根源：本地 go mod init 随手写了 go mod init myapp，但代码里 import 的却是 "github.com/yourname/repo/pkg"，Go 会直接拒绝解析——因为模块路径必须和 import 路径严格一致，否则校验失败、下游无法拉取、go get 报 checksum mismatch。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
Golang Google Wire
下载
在 Go 中使用 google/wire 实现编译时依赖注入——wire.NewSet、wire.Build、wire.Bind（接口→实现）、wire.Struct、wire.Value、wire.Interface
- 初始化前先删掉残留：
rm -f go.mod go.sum vendor/ Gopkg.lock - 用真实托管路径初始化：
go mod init github.com/yourname/repo（哪怕还没 push，只要未来会放这里） - 如果已推到私有 GitLab，路径含子组（如
gitlab.example.com/group/subgroup/project），module 名必须完整包含subgroup，漏一个就报错 - 改完
go.mod第一行后，立刻执行go mod tidy，让 Go 重新扫描 import 并同步依赖图
replace 路径写错导致构建失败或 CI 崩溃
replace 是调试私有模块或本地修改时的刚需，但写错路径会直接让 go build 找不到包，或在 CI 环境因路径不存在而彻底失败。尤其注意：它不支持 ~/ 展开、不接受相对路径外的模糊写法、目标目录必须含 go.mod。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 用相对于当前
go.mod的路径，例如：replace github.com/you/utils => ../utils（不是./../utils或~/dev/utils） - 被 replace 的目录必须已运行过
go mod init，否则 Go 会 fallback 到 legacy 模式，解析行为不可控 - CI 构建前建议清理临时 replace：
go mod edit -dropreplace=github.com/you/utils - 别把 replace 当长期方案——上线前务必删掉，否则别人 clone 后构建直接失败
GOPRIVATE 配置缺失导致私有模块拉取超时或 403
访问公司内网 Git 仓库时，Go 默认走 GOPROXY，结果要么连不上（timeout），要么认证失败（403）。这不是网络问题，而是 Go 没被告知“这个域名下的模块不能走代理”。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 设环境变量：
export GOPRIVATE=git.company.com,gitlab.internal（多个域名用逗号分隔，不加https://） - 配合
GONOSUMDB跳过校验：export GONOSUMDB=git.company.com（否则私有模块无 checksum 记录，go build -mod=readonly直接报错） - 验证是否生效：执行
go env GOPRIVATE，输出应为设定值；再跑一次go get private/repo@main，不再走 proxy 就对了 - 别只配 shell，CI 脚本里也要显式 export，否则本地能跑、流水线炸锅
go build 仍报 no required module provides package
这个错误表面是“找不到包”，本质是模块路径链断了——可能 go.mod 里没 require 对应模块、replace 写错、或上游模块本身 module 声明和 import 不一致。它常出现在引入 Hertz、Kitex 等框架子包时。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 先确认是否真没初始化模块：
go list -m报go: not in a module就得先go mod init - 看报错里的 import 路径（如
github.com/cloudwego/hertz/pkg/app），去对应仓库查它是否真的导出这个包——有些子包路径在 v0.5.0 后变更，旧 import 已失效 - 手动补依赖：
go get github.com/cloudwego/hertz@v0.8.0（不是子包路径，而是主模块路径 + 版本） - 如果用了
replace，检查是否覆盖了该模块的正确版本，导致子包路径解析失败
~/go/pkg/mod 里的旧版本、CI 缓存的 go.sum、甚至 IDE 的 gopls 索引都可能固化一个错误路径状态。每次改完 go.mod，最好清缓存再试：go clean -modcache。 
