Go版本需≥1.18，否则报“cannot find main module”；应先用go version检查，再升级Go并新建空目录执行go mod init初始化模块。
Go 版本必须 ≥1.18，低于这个会报 go: cannot find main module
很多新手卡在这一步，不是 Gin 装不上，而是 Go 太老。用 go version 检查，如果输出是 go1.17.x 或更低，直接升级。Mac 用户用 brew install go，Linux 用户建议下载官方二进制包解压到 /usr/local/go 并更新 PATH。Windows 用户从官网下载 MSI 安装包即可。旧版本 Go 无法正确解析 Go Modules，后续所有命令都会失败。
go mod init 必须在空目录执行，且模块名不能含空格或中文
别在已有代码的目录下硬跑 go mod init，它不会帮你清理旧依赖，反而可能生成错误的 go.mod。新建干净目录：mkdir my-api && cd my-api，再运行 go mod init example.com/my-api。模块名只是逻辑标识，不一定要对应真实域名；但不能写成 my api 或 我的项目，否则 go get 会解析失败。执行后你会看到 go.mod 文件，内容里有 module example.com/my-api 和 go 1.21（版本由当前 Go 决定）。
go get github.com/gin-gonic/gin 不要加 -u
加 -u 会强制升级 Gin 及其所有间接依赖到最新版，容易引发兼容问题——比如 gin.H 类型在 v1.9+ 后改为 map[string]any，而旧教程仍用 map[string]interface{}，编译直接报错。只运行 go get github.com/gin-gonic/gin 即可拉取兼容当前 Go 版本的稳定版。装完检查 go.mod，里面应该有类似 github.com/gin-gonic/gin v1.9.1 的行。不确定是否装对？删掉 go.sum，再跑一次 go mod tidy，它会自动补全并锁定依赖。
启动前确认 gin.Default() 和 r.Run() 的端口监听行为
gin.Default() 自带 Logger 和 Recovery 中间件，适合开发调试；如果想静默启动（比如配合 IDE 调试器），改用 gin.New()。r.Run() 默认监听 :8080，但如果你本地 8080 被占用，别手动改代码——直接传参：r.Run(":9090")。注意冒号不能漏，写成 "9090" 会 panic 报错 listen tcp: address 9090: missing port in address。启动后访问 http://localhost:8080/ping，返回 JSON 就算通了；如果浏览器显示“拒绝连接”，先 curl -v http://localhost:8080/ping 看是否服务真没起来，而不是立刻怀疑路由写错了。
Gin 本地环境真正难的不是装包，而是路径、权限、代理、端口这四个点交叉出问题。每次卡住，优先检查当前目录是否干净、go.mod 是否生成成功、go run . 输出的第一行有没有 cannot load 或 undefined 字样。
