go mod init 必须在项目根目录执行，因为go.mod是模块唯一锚点，Go工具链向上查找首个go.mod确定模块边界；若在子目录执行会导致模块路径错误、import不匹配及“cannot find module”等构建失败。
go mod init 为什么必须在项目根目录执行
因为 go mod init 生成的 go.mod 文件会作为整个模块的“锚点”，Go 工具链从当前目录向上查找最近的 go.mod 来确定模块边界。如果在子目录下误执行，会导致模块路径错误、依赖解析失败，甚至 import 路径和实际目录结构不一致。
常见错误现象：cannot find module providing package github.com/gin-gonic/gin 或 import "xxx" is a program, not an importable package，往往就源于此。
- 项目根目录应是包含
main.go的最外层文件夹（如myapp/），不是myapp/cmd/或myapp/internal/ -
go mod init后的模块名（如myapp或github.com/you/myapp）会成为所有内部包的导入前缀，影响后续所有import语句 - 若已误初始化，删掉错误目录下的
go.mod和go.sum，回到正确根目录重跑go mod init your_module_name
gin 引入后 go mod tidy 报错的典型原因
go mod tidy 报错通常不是 gin 本身的问题，而是模块环境没对齐。最常踩的坑是 GOPATH 和 Go Modules 冲突，或代理未生效。
典型报错：go: github.com/gin-gonic/gin@v1.10.0: reading https://proxy.golang.org/github.com/gin-gonic/gin/@v/v1.10.0.mod: 404 Not Found，说明代理没走通；go: github.com/gin-gonic/gin@v1.10.0: Get "https://sum.golang.org/lookup/...": dial tcp: lookup sum.golang.org: no such host，说明网络或代理配置失效。
立即学习“go语言免费学习笔记（深入）”；
- 先确认
GO111MODULE=on：运行go env GO111MODULE，输出必须是on，不是auto或空 - 国内必须设代理：
go env -w GOPROXY=https://goproxy.cn,direct（注意逗号后是direct，不是https://goproxy.io等旧地址） - 如果项目在
$GOPATH/src下，go mod会拒绝工作——直接把项目挪到$HOME/myproject这类非 GOPATH 路径下再试
vendor 目录要不要？什么时候用 go mod vendor
绝大多数 Gin 项目不需要 vendor。它只在极少数场景有用：离线构建、CI/CD 环境无法访问公网代理、或团队强制要求所有依赖锁定在代码库内。
用了 vendor 反而容易出问题：比如忘记更新、go mod vendor 后又手动改了 go.mod 却没重新 vendor，导致本地跑得通但 CI 失败。
- 日常开发和部署推荐不启用 vendor：删掉
vendor/目录，确保go build时能正常拉取依赖 - 真要用，必须配合
-mod=vendor构建：go build -mod=vendor -o app ./cmd，否则 Go 仍会忽略vendor去查远程 -
go mod vendor不会自动更新go.mod或go.sum，它只是把当前go.mod记录的依赖拷过去，所以务必先go mod tidy再vendor
为什么 go get github.com/gin-gonic/gin 没反应或标红
不是 gin 安装失败，而是你没触发依赖写入。Go Modules 下，go get 默认只下载，不修改 go.mod ——除非你加 -d 或让它被代码引用后自动补全。
现象：命令执行完没报错，但 go.mod 里没有 github.com/gin-gonic/gin，IDE 依然标红 import 行。
- 最稳妥做法：先写好
import "github.com/gin-gonic/gin"，再运行go mod tidy，它会自动添加 require 并下载 - 想提前拉取并写入：
go get -d github.com/gin-gonic/gin@latest（-d表示只下载不构建） - 避免用
go get -u：它会升级所有间接依赖，可能引入不兼容变更，Gin v1.x 升级到 v2 需要手动改 import 路径
go.mod 是否真实反映代码里的 import 关系——这三个点卡住，后面所有路由、中间件、JSON 绑定都跑不起来。 
