根本原因是Go Modules未正确拉取依赖：go get不保证写入当前模块，需在项目根目录执行go mod tidy自动补全依赖并下载，配合GOPROXY代理设置（如https://goproxy.cn,direct）和GO111MODULE=on。
go run main.go 报错找不到 gin 包
根本原因不是 Gin 安装失败，而是 Go Modules 没正确拉取依赖。go get 命令本身不保证把包写进当前模块——尤其当你没进项目目录、或没设 GO111MODULE=on 时，它可能默默装到 GOPATH 下，对当前项目无效。
实操建议：
- 先确认在项目根目录下执行命令，
ls go.mod要能看见文件 - 运行
go mod tidy—— 它会自动检查 import、补全go.mod并下载缺失依赖，比go get更可靠 - 国内环境必须设代理：
export GOPROXY=https://goproxy.cn,direct（macOS/Linux）或set GOPROXY=https://goproxy.cn,direct（Windows CMD） - 如果
go mod tidy卡住或报unknown revision，大概率是内网/代理没配GOPROXY或GO111MODULE=on
router.Run() 启动失败：bind: address already in use
这是最常被忽略的端口冲突问题。r.Run() 默认监听 :8080，但很多开发工具、旧进程、甚至 Docker 容器都可能占着这个端口。
实操建议：
- 别依赖默认端口，显式指定一个冷门端口测试：
r.Run(":8081")或r.Run("127.0.0.1:9000") - 查占用：
lsof -i :8080（macOS/Linux）或netstat -ano | findstr :8080（Windows），再用kill -9 <PID>或任务管理器结束进程 - 绑定
0.0.0.0在生产环境有安全风险，本地调试用没问题；若需外网访问，务必加防火墙或反向代理层
启动后访问 404 或 favicon.ico 报错
这不是 Gin 启动失败，而是路由或静态资源没配对。Gin 不会自动处理 /favicon.ico，浏览器会默认发一次 GET 请求，没匹配路由就 404 —— 这属于正常现象，不影响主逻辑，但影响日志干净度和前端体验。
实操建议：
- 加 favicon 中间件：
go get github.com/thinkerou/favicon，然后r.Use(favicon.New("./static/favicon.ico")) - 静态文件服务要显式声明：
r.Static("/static", "./static")，路径必须存在且有读权限，注意大小写（Linux 区分） - 检查路由注册是否在
r.Run()之前；常见错误是把r.GET()写在r.Run()后面，那条路由永远注册不上 - 用
curl -v http://localhost:8080/测试，避开浏览器自动追加 favicon 的干扰
控制台输出 [GIN-debug] WARNING 但服务能跑
这类日志不阻断启动，但暴露了潜在风险点。比如 [WARNING] You trusted all proxies 是安全配置缺失，[WARNING] Running in "debug" mode 是生产环境大忌。
实操建议：
- 关 debug 模式：
gin.SetMode(gin.ReleaseMode)放在gin.Default()之前，或设环境变量GIN_MODE=release - 信任代理要收敛：
r.SetTrustedProxies([]string{"10.0.0.0/8", "192.168.0.0/16"})，别留空或填nil -
gin.Default()自带Logger和Recovery，生产环境若已有统一日志系统（如 Sentry + Zap），该换用gin.New()手动挂载中间件，避免日志重复或 panic 处理逻辑打架
go run main.go，别依赖 IDE 缓存的旧状态。 
