go:generate 仅是代码生成触发器，非包管理器；应优先用 go install 显式安装并锁定工具版本，避免依赖远程下载；推荐用 Makefile 封装调用以增强可控性与可调试性。
go:generate 不能替代真正的工具依赖管理
它只是代码生成的触发器，不是包管理器。你写 //go:generate go run github.com/swaggo/swag/cmd/swag@v1.16.2，Go 会临时下载并运行那个版本的 swag，但不会把它装进 $GOPATH/bin 或项目本地 bin/ 目录，也不会记录在 go.mod 里——下次 go generate 还得重新拉一遍，网络差或模块被删就会失败。
- 真正需要复用的工具（比如
mockgen、stringer、protoc-gen-go），应该用go install显式安装，并锁定版本：go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.34.2 -
go:generate行里尽量别写带@vX.Y.Z的 URL；如果非写不可，确保 CI 环境的 Go 版本 ≥ 1.21（否则不支持模块路径后缀） - CI 中若禁用了代理或 GOPROXY，
go:generate里带远程 URL 的行大概率直接报module github.com/xxx not found
go run xxx@version 在模块外执行会污染全局构建缓存
执行 go run github.com/corp/cli/cmd/tool@v0.3.1 时，Go 会把该工具编译产物缓存在 $GOCACHE 下，但缓存 key 包含完整模块路径 + 版本 + 构建参数。如果你在多个项目里用不同版本跑同一个工具（比如 v0.3.1 和 v0.3.2），它们不会冲突；但如果你在没 go.mod 的目录下跑，Go 会 fallback 到“无模块模式”，此时缓存行为不稳定，偶尔会复用错对象文件，导致生成结果异常（比如 struct tag 没生效）。
- 始终在有
go.mod的项目根目录下执行go generate或go run - 避免在
vendor/已启用的项目中混用go run xxx@version；Go 可能忽略vendor/直接走模块，造成依赖不一致 - 调试时想看具体命令干了啥？加
-x：go run -x github.com/swaggo/swag/cmd/swag@v1.16.2
用 Makefile 或 justfile 封装工具调用更可控
把工具链逻辑从 //go:generate 挪到 Makefile 里，能显式控制环境变量、工作目录、超时和错误处理，也方便本地开发时单独重跑某一步。
- 例如，不写
//go:generate go run github.com/golang/mock/mockgen@v1.6.0 -source=store.go，而是写//go:generate make mock，然后在Makefile里定义：mock: go install github.com/golang/mock/mockgen@v1.6.0 mockgen -source=store.go -destination=mock_store.go
-
go:generate不支持条件判断或变量展开，而 Makefile 可以用$(shell go list -m -f '{{.Version}}' github.com/golang/mock/mockgen)动态读版本 - 团队协作时，统一入口还能避免有人手敲
go run忘了加@vX.Y.Z，导致本地和 CI 结果不一致
go install 到 ./bin 是最简单的本地化方案
与其每次 go run xxx@vN 都等下载编译，不如一次性装进项目目录下的 ./bin，再让 go:generate 调用本地二进制。这样既快又确定，还能 git track 工具版本（通过 ./bin/.tool-versions 或 README 记录）。
- 初始化：
mkdir -p ./bin && export PATH="$(pwd)/bin:$PATH" && go install github.com/kisielk/errcheck@v1.7.0 - 生成注释改用：
//go:generate errcheck -ignore='Close' ./... - 注意
go install默认装到$GOBIN，必须提前设GOBIN=$(pwd)/bin才能落到项目内 - Git 提交
./bin/errcheck不现实（二进制太大），但可以提交tools.go文件，用空导入强制go mod tidy记录工具版本：package tools import ( _ "github.com/kisielk/errcheck@v1.7.0" )
go:generate 报错却不知道它背后到底执行了什么命令，也没留日志——这时候翻 go run -x 输出比猜快得多。 
