根本原因是模块路径未对齐：go.mod 中的 module 声明必须与 import 路径完全一致，否则 Go 工具链拒绝解析；本地文件路径不影响 import 语义，import 必须匹配 module 路径前缀。
go mod init 之后为什么 go run 还报 “package not found”
根本原因不是没装库，而是模块路径没对齐。Go 在 go.mod 里记录的是模块根路径（module path），而代码里 import 的路径必须和它一致，否则 Go 工具链会拒绝解析。
- 执行
go mod init example.com/myapp后，所有import必须以example.com/myapp/...开头（比如example.com/myapp/utils），不能写成./utils或myapp/utils - 如果项目在
$HOME/myapp，但go mod init用了github.com/you/myapp，那后续import "github.com/you/myapp/utils"才合法——本地路径不影响 import 路径语义 -
go run .会自动找当前目录下的main.go，但它不改变 import 解析规则；报错时先检查go.mod第一行的 module 声明是否和 import 完全匹配
加一个库为什么 go mod tidy 拉了一堆间接依赖
Go 不做“扁平化依赖”，而是按最小版本选择（Minimal Version Selection, MVS）递归求解整个依赖图。你显式 require 的库 A 可能依赖 B v1.2，而另一个库 C 依赖 B v1.5，最终 go mod tidy 会选择 B v1.5（满足两者），并把 B 标记为 // indirect —— 因为你没直接 import B。
- 运行
go mod graph | grep b-name可查谁引入了某个间接依赖 - 想锁定某间接依赖版本？直接
go get b-name@v1.2，它会从// indirect升级为显式 require - 不要手动删
go.sum行：校验失败时go build会直接报错，且无法跳过
开发中要改第三方库源码，怎么热替换不发 PR 就能用
用 replace 指令重定向模块路径到本地目录，比 fork + replace + go get 更快，且不污染远程引用。
replace github.com/some/lib => ../my-fix-lib
- 路径必须是绝对路径或相对于
go.mod的相对路径（推荐后者） - 被 replace 的模块仍需出现在
require中，否则go mod tidy会把它删掉 - 改完本地代码后，不需要重新
go mod tidy，go run或go build会自动读取新代码 - 上线前务必删掉
replace并验证原版行为，否则 CI 构建会失败（因为没上传你的本地目录）
CI 环境里 go build 失败，提示 checksum mismatch
常见于团队协作中有人手动改了 go.sum、或用了未发布的 commit hash（比如 go get github.com/x/y@abcd123），导致校验和与官方 proxy 返回的不一致。
- CI 应始终运行
go mod download+go mod verify作为前置检查 - 本地修复：先
go clean -modcache清缓存，再go mod tidy -v查哪行 sum 不匹配，最后go mod download重拉 - 避免用 commit hash 引依赖：优先用 tag，实在要用也得配合
go mod edit -replace显式固定，并同步更新go.sum
模块路径拼写、replace 的生命周期、sum 校验的触发时机——这三处出问题的概率远高于语法错误，盯住它们，Go 依赖就没大坑。
