Go环境安装后必须验证三件事：go version≥1.20、GOPATH/GOROOT路径正确且$GOPATH/bin在PATH中、go list -m all在空目录返回main；脚手架应不覆盖main.go，模块名须为合法域名前缀，初始化后需清理冗余中间件和硬编码配置。
Go 语言环境装好不等于能高效开工，真正卡住进度的往往是项目初始化那几分钟：该用什么目录结构？go mod init 的模块名怎么写才不踩坑？Gin、GORM、Zap 这些依赖是手动 go get 还是靠工具生成？答案很直接：环境必须干净，脚手架必须可复用、可定制、不带隐藏抽象层。
Go 环境安装后必须验证的三件事
很多人装完 Go 就以为万事大吉，结果在 go mod 或 cobra-cli 初始化时突然报错。不是版本问题，而是环境变量没生效或路径冲突。
-
go version输出的版本号必须 ≥ 1.20（2026 年主流项目已普遍要求 1.21+） -
go env GOPATH和go env GOROOT要能正常打印，且$GOPATH/bin必须在系统PATH中（否则cobra-cli、gf、goctl都找不到） - 执行
go list -m all在空目录下应返回main，而不是报no modules found—— 后者说明GO111MODULE没开启或被覆盖
脚手架选型不能只看“一键生成”，要看它改不改你的 main.go
几乎所有 CLI 脚手架（cobra-cli init、gf init、goctl api new）都会尝试覆盖或重写 main.go。但你已有项目很可能在里头做了信号处理、配置热加载、或自定义日志初始化 —— 这些逻辑一旦被覆盖就很难还原。
-
cobra-cli init会提示main.go already exists. Overwrite? [y/N]，选N后需手动把cmd.Execute()嵌入原main.go，注意调用顺序（比如logger.Init()必须在cmd.Execute()前） -
gf init demo会新建完整目录，不碰你原有代码，适合新项目；但若想迁入现有工程，得自己抄config/、internal/结构，别直接 mv -
webkit和godogen是纯模板复制型工具，不侵入任何已有文件，生成后全由你决定哪些文件保留、哪些删掉 —— 对老项目集成最安全
go mod init 的模块名不是随便写的
模块名不是项目文件夹名，也不是 GitHub 用户名加仓库名的简单拼接。它决定了后续所有 import 路径是否可解析、go get 是否能正确拉取本地包、甚至 Wire 依赖注入能否识别 provider 函数。
立即学习“go语言免费学习笔记（深入）”；
- 如果项目要开源或被其他模块引用，模块名必须是可解析的域名前缀，例如
github.com/your-org/your-project，不能是myapp或./myapp - 如果只是内部服务，且确定永不发布，可用
example.com/your-team/your-service—— 只要和公司内其他项目不冲突即可 - 模块名含大写字母（如
MyApp）会导致go build报错：invalid module path "MyApp": leading capital letter - 初始化后立即执行
go mod tidy，观察输出里有没有require行被自动添加；如果没有，说明模块名可能被 Go 认为是本地路径而非远程模块
生成后第一件该做的事：删掉不需要的中间件和示例路由
所有脚手架为了“开箱即用”，默认塞了一堆你暂时用不上的东西：JWT 验证中间件、Swagger 文档路由、健康检查端点、邮件通知 stub。它们不是 bug，但会干扰你对核心流程的理解。
- 先注释掉
router.Use(...)里所有非必需中间件（比如auth.Middleware()、metrics.Middleware()），只留日志和 panic 恢复 - 删掉所有
/swagger、/healthz、/debug/pprof相关路由注册，避免暴露调试接口到生产环境 - 检查
config.yaml或viper加载逻辑：如果脚手架默认读./config.yaml，但你实际要用env变量，就得立刻改掉加载方式，别等部署时报open config.yaml: no such file
最容易被忽略的是：脚手架生成的代码里往往藏着硬编码的数据库地址、Redis 密码、或 RocketMQ broker 地址。这些值通常在 config/ 下某个 YAML 文件里，但没人会替你改成自己的测试环境 —— 它们就静静躺在那里，直到你第一次 go run main.go 报连接超时才意识到。
