迁移后依赖报错主因是缓存、代理或路径未同步，删缓存、换代理、重设模块名三步可解决80%问题；需删旧锁文件、显式go mod init、用replace修复gopkg.in等重定向路径，并确保import与module声明严格一致。
迁移后依赖报错，大概率不是代码问题，而是模块缓存、代理配置或路径声明没同步更新。直接删缓存、换代理、重设模块名这三步做完，80% 的报错就消失了。
go mod init 失败：unknown revision 或路径不匹配
旧项目用 dep/glide 管理时，Gopkg.lock 里常存分支名、哈希或非语义化 tag（如 v1.2.3-beta），而 Go Modules 只认标准 vX.Y.Z 格式 tag，且要求 import 路径与 go.mod 第一行的 module 声明严格一致。
- 删掉残留锁文件：
rm -f Gopkg.lock glide.lock - 显式初始化模块：
go mod init github.com/your-org/your-repo（别依赖自动猜测） - 若代码中用了
gopkg.in/yaml.v2这类重定向路径，必须手动加replace：replace gopkg.in/yaml.v2 => gopkg.in/yaml.v2 v2.4.0
- 执行
go list -m all检查是否还有间接残留——有就说明 vendor/ 或旧缓存还在干扰
go mod tidy 报 missing go.sum entry 或 checksum mismatch
模块 zip 包下载成功了，但 go.sum 缺少对应校验和，常见于代理返回包但没同步提供 checksum，或你手动删过 go.sum 某行。
- 先定位具体模块：
go mod download -v，看哪一行输出带missing或checksum mismatch - 临时切回官方源验证：
GOPROXY=https://proxy.golang.org,direct go mod tidy - 确认模块合法但只是校验丢失？删掉
go.sum，再跑go mod tidy（仅限本地开发，CI 中禁用） - 私有模块必须配对设置：
GOPRIVATE=git.internal.com+GONOSUMDB=git.internal.com，否则仍会尝试连公网 sumdb
no required module provides package 错误但路径明明存在
这不是网络问题，是模块路径和 import 不一致。Go 工具链只认 go.mod 里声明的 module 前缀，哪怕物理路径对也无效。
- 检查
go.mod首行：module github.com/myorg/app→ 所有import必须以该字符串开头 - 禁止用
./internal/handler这种相对路径 import，全部改为import "github.com/myorg/app/internal/handler" - 批量修复命令（替换为你的真实模块名）：
gofmt -r 'import "./(.*?)" -> import "github.com/myorg/app/$1"' -w . -
replace右侧不能写./local/lib，只接受绝对路径或上层含go.mod的 Git 仓库（如../mylib）
go build 卡住或 timeout，但 git clone 正常
代理没生效，或 GOPROXY/GOSUMDB 配置不匹配。Go 下载走 GOPROXY，校验却独立走 GOSUMDB，两者必须协同。
- 国内环境推荐：
go env -w GOPROXY=https://goproxy.cn,direct - 私有库必须加：
go env -w GOPRIVATE=git.internal.com - 若校验失败，临时关掉：
go env -w GOSUMDB=off（上线前必须恢复） - IDE 内置终端不继承 shell 环境变量，需在 IDE 终端里单独执行
go env -w GOPROXY=... - 验证是否生效：
go env GOPROXY和go mod download -v看日志里拉取地址
最易被忽略的是缓存残留和 IDE 环境隔离——go clean -modcache 后，别忘了在 Goland/VSCode 的终端里也重设一遍 GOPROXY，否则本地能通、IDE 里照样报错。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
