go mod init 必须在项目根目录执行，否则会导致 import 路径与 go.mod 模块名不匹配、IDE 无法识别模块、CI 依赖树错误；正确做法是先 cd 到项目根目录再运行 go mod init github.com/yourname/myservice。
Go 环境搭建本身不直接提升架构能力，但错误或随意的配置会埋下长期隐患——比如 GOROOT 和 GOBIN 混用、go mod 初始化位置错乱、多项目共用未隔离的 GOPATH，都会让后续模块拆分、依赖收敛、CI 构建变得脆弱。
为什么 go mod init 必须在项目根目录执行
这是最容易被跳过的一步，但直接影响整个项目的可维护性。如果在子目录（如 src/ 或 internal/）里运行 go mod init，会导致：
-
go.mod路径与实际 import 路径不一致，引发import "myproject/internal/handler"找不到包的错误 - IDE（如 Goland）无法正确识别模块边界，跳转和重构失效
- CI 流水线中
go list -m all无法准确输出依赖树，影响安全扫描和版本审计
正确做法：先 mkdir myservice && cd myservice，再 go mod init github.com/yourname/myservice。模块名必须是完整路径，且与未来 import 语句完全一致。
GOROOT 和 GOPATH 在 Go 1.16+ 中的真实分工
很多人还在手动设置 GOPATH，其实现代 Go 已不需要它参与构建逻辑。关键区别是：
立即学习“go语言免费学习笔记（深入）”；
-
GOROOT是 Go 安装目录（如/usr/local/go），只读，不应改动；它存放stdlib和编译器工具链 -
GOPATH默认为$HOME/go，仅用于go get（已弃用）或旧式非模块项目；Go Modules 启用后，依赖下载到$GOPATH/pkg/mod，但项目自身不再依赖该路径 - 真正影响开发体验的是
PATH：必须包含$GOROOT/bin（供go命令）和$GOBIN（供go install输出的二进制）
建议在 ~/.zshrc 中只保留：export PATH=$PATH:/usr/local/go/binexport GOBIN=$HOME/go/binexport PATH=$PATH:$GOBIN
多项目共存时如何避免依赖污染
当同时维护多个 Go 微服务（如 user-svc、order-svc），常见错误是全局 go get -u 升级所有依赖。这会导致：
- 某个服务因
github.com/gin-gonic/gin v1.9.1升级到v1.10.0而出现中间件签名变更，panic 报错 -
go.sum校验失败，CI 构建中断 - 本地调试正常，但 Docker 构建时因缓存复用旧 layer 导致行为不一致
正确做法：
- 每个服务独立
go mod init，互不共享go.mod - 升级依赖时，进到对应项目目录，执行
go get github.com/gin-gonic/gin@v1.10.0（带版本号） - 用
go mod graph | grep gin检查是否意外引入了其他版本 - Dockerfile 中始终使用
go mod download显式拉取依赖，而非依赖构建缓存
环境变量错配导致的典型 panic 场景
最隐蔽的问题之一：本地能跑，CI 失败，报错类似 cannot find module providing package github.com/xxx/yyy。根本原因常是：
-
GO111MODULE=off被意外启用（尤其在某些 CI 镜像中默认关闭），导致 Go 忽略go.mod，退化回 GOPATH 模式 -
CGO_ENABLED=0在需要 cgo 的项目（如 SQLite、某些 TLS 库）中被强制设为 0，编译失败 -
GOPROXY配置成私有代理但未认证，go mod tidy卡住超时
检查方式：go env GO111MODULE 应输出 on；go env GOPROXY 推荐设为 https://proxy.golang.org,direct（国内可加 https://goproxy.cn）；go env CGO_ENABLED 按需设为 1 或 0，不要全局硬编码。
真正的架构能力不是靠堆砌组件，而是从 go mod init 的第一行开始，就对模块边界、依赖生命周期和构建确定性保持敏感。这些细节不会立刻暴露，但会在三个月后的上线前夜集中爆发。
