go mod 是模块版本与依赖关系的声明和协调机制；根源问题在于写错 go.mod、跳过 go mod tidy 或沿用 GOPATH 思维。必须在项目根目录执行 go mod init，模块名需与 import 路径完全匹配；go mod tidy 是唯一可信的依赖同步命令，会自动增删依赖、应用 MVS 算法并更新 go.sum；import 路径基于模块名而非本地路径；replace 和 exclude 是移植性雷区，仅限临时调试；go.mod 是契约文件，修改前须确保他人可一键构建成功。
go mod 不是“装包工具”，而是模块版本与依赖关系的声明和协调机制；你写错 go.mod、跳过 go mod tidy、或在 GOPATH 时代思维下乱放代码，才是绝大多数包管理问题的根源。
go mod init 放错位置？项目根目录必须是模块起点
很多新手在子目录里执行 go mod init，结果生成的模块路径和实际 import 路径对不上，导致编译报 import "xxx" not found。
- 必须在项目最外层目录（即
main.go所在目录）运行go mod init your-module-name - 模块名不一定要和 GitHub 路径一致，但要和代码中
import的路径完全匹配（比如import "myapp/config"，那模块名就得是myapp） - 如果项目已有
import语句，建议用go mod init后立刻跑go build验证是否能解析所有包
go mod tidy 不只是“下载依赖”，它会重写 go.mod 和校验 go.sum
go mod tidy 是唯一可信的依赖同步命令——手动改 go.mod、只用 go get、或跳过它直接 go build，都会让依赖状态失控。
- 它会扫描全部
.go文件中的import，删掉未使用的依赖，补上缺失的依赖 - 它会自动选择满足所有约束的最低兼容版本（MVS 算法），不是“最新版”也不是“你想要的版”
- 它会更新
go.sum，确保下次构建时校验通过；若跳过，CI 构建可能因哈希不匹配失败 - CI 流程中应强制加
go build -mod=readonly，防止意外修改go.mod
import 路径 ≠ 本地文件路径，更不等于 GOPATH/src 下的路径
Go Modules 模式下，import "github.com/gin-gonic/gin" 对应的是全局缓存里的 $GOPATH/pkg/mod/github.com/gin-gonic/gin@v1.9.1/，和你的项目目录、$GOPATH/src 完全无关。
- 不要再把项目硬塞进
$GOPATH/src，也不用设置GO111MODULE=off - 自定义包的
import必须使用模块名开头，例如模块声明为module myapp，内部子包就该写import "myapp/utils"，而不是import "./utils"（后者非法） - 函数/类型首字母小写 = 不可导出，
import后也无法访问；这是包可见性规则，和路径无关
replace 和 exclude 不是“快捷修复”，而是移植性雷区
用 replace 把线上依赖指向本地路径或 fork 分支，短期方便，但会让别人 clone 你的项目后无法直接构建。
- 仅限调试或临时绕过 bug，上线前务必删掉
replace并验证原依赖是否可用 -
exclude会强制忽略某个依赖版本，可能破坏其他包的兼容性假设，极少需要 - 真正安全的替代方案是：提 PR 修复上游、等新版本发布、或用
go get xxx@commit锁定已验证的提交
go.mod 是一份**契约文件**——它既约束你的代码怎么被别人 import，也声明了你依赖谁、以什么版本。改它之前，先问一句：这个改动，别人拉下来还能不能一键构建成功？ 
