项目级Go版本切换必须用.tool-versions+asdf，go.work是多模块协作唯一安全路径，跨模块引用须通过go.work而非硬编码路径或replace。
项目级 Go 版本切换必须靠 .tool-versions + asdf
手动改 GOROOT 或反复编辑 PATH 会导致终端、IDE、CI 流水线看到的版本不一致，尤其当你同时开着 VS Code 窗口调试 auth-service（要 Go 1.20）和 payment-service（要 Go 1.22）时，go version 输出可能随机漂移。
真正起效的方式只有一种：在每个项目根目录（即含 go.mod 的目录）放一个 .tool-versions 文件，内容严格为：
golang 1.20.14
然后确保：
-
~/.asdf/shims在$PATH最前面，且已source过 shell 配置文件 - 运行过
asdf reshim golang（换版本后必做） -
asdf current golang在项目目录下应显示对应版本，不是unset - VS Code 需启用
asdfshell 集成插件，否则gopls仍用系统默认 Go
go.work 是多模块协作的唯一安全路径
当多个服务共存于同一仓库（比如 ./auth、./payment、./shared），直接用相对路径导入（如 import "../shared"）会让 go build 和 gopls 行为分裂——前者报错“no required module provides package”，后者跳转失败。
立即学习“go语言免费学习笔记（深入）”；
正确做法是统一用 go.work 声明参与开发的模块：
在 Go 中使用 google/wire 实现编译时依赖注入——wire.NewSet、wire.Build、wire.Bind（接口→实现）、wire.Struct、wire.Value、wire.Interface
- 在仓库根目录执行
go work init - 逐个添加：
go work use ./auth ./payment ./shared - 生成的
go.work文件必须提交，但 CI 构建时需显式禁用：go build -modfile=go.mod - VS Code 打开整个仓库时，必须用 Multi-root Workspace 并确认每个 folder 的
go.toolsEnvVars指向正确模块根目录
依赖隔离不靠虚拟环境，靠 go mod + 目录上下文
Go 没有 venv 或 node_modules 概念。所谓“环境隔离”，本质是 Go 工具链根据当前工作目录自动匹配最近的 go.mod 文件来解析依赖。
这意味着：
- 每个子项目必须有自己独立的
go.mod，不能靠父目录一个go.mod管理全部 - 禁止把多个项目塞进
$GOPATH/src——哪怕设置了GO111MODULE=on，旧路径残留仍可能干扰go list -m all -
go mod vendor不是必需操作，仅在离线构建或审计锁定时才用；日常开发依赖始终走$GOCACHE，无需复制 - 跨模块引用必须走
go.work，而非硬编码路径或修改replace指令——后者会让go.sum失效且无法被 CI 识别
Docker 中多版本并行开发要绕过 GOROOT 陷阱
容器内硬编码 GOROOT=/usr/local/go 会锁死版本，一旦镜像里装的是 Go 1.21，你就没法在同一个容器里跑 Go 1.22 的测试。
可行方案是：
- 用多阶段构建，在
BUILD阶段按需下载指定 Go 版本到临时路径，编译完即丢弃 - 用
docker-compose.yml为不同服务指定不同基础镜像：golang:1.20-alpinevsgolang:1.22-slim - 自定义镜像预装
delve和air，但二进制必须与镜像内 Go 版本 ABI 兼容，不能混用 - Makefile 封装命令时，避免写死
go run，改用docker run --rm -v $(PWD):/app -w /app golang:1.22 go run .
真正容易被忽略的是 IDE 调试器连接：Delve 容器必须与目标 Go 版本完全匹配，否则 could not launch process: unsupported version of Go 错误会卡住调试流程。
