直接说结论：别用 go build 单干，用 Makefile 封装构建逻辑，但必须显式指定包路径、分离依赖管理、避免隐式环境干扰。
go build 在 Makefile 里不写包路径就失败
Go 默认只编译当前目录下的 main 包。项目结构通常是 cmd/myapp/main.go，而 Makefile 在根目录，go build 不带参数就会报 no Go files in .。
- 错误写法：
go build -o bin/app（当前目录没main.go） - 正确写法：
go build -o bin/app ./cmd/myapp（明确指向包路径） - 别用
cd cmd/myapp && go build：shell 环境易被并发或子 shell 干扰，路径不可靠 - 变量化输出名更安全：
BIN_NAME ?= app，后续用$(BIN_NAME)，方便 CI 复用
deps 和 build 必须拆开，不能塞进同一个 target
把 go mod tidy 放进 build 会导致每次编译都改 go.sum，CI 缓存失效、PR diff 泛滥，还可能因网络问题中断构建。
- 单独定义
depstarget：deps: go mod tidy && go mod download - 所有构建类 target 显式声明依赖：
build: deps，确保依赖就绪再执行 - 加个
verify-mod检查是否干净：git status --porcelain go.mod go.sum | grep -q '^??'，有输出说明需要提交 - CI 流水线里显式调用
make deps，开发时只在增删 import 后手动运行
交叉编译多个平台时，GOOS/GOARCH 别硬写六遍
手动写 GOOS=linux GOARCH=amd64 go build、GOOS=windows GOARCH=386 go build……既难维护又容易漏平台，输出名也容易混淆。
- 用变量定义平台列表：
OSARCHS = linux/amd64 linux/arm64 windows/amd64 - 用
$(foreach ...)动态生成 target：$(eval $(call build-target,$(osarch))) - 每个 target 命名为
build-linux_amd64，支持通配调用：make build-% - 输出文件名必须区分平台：
-o bin/$(BIN_NAME)-$(osarch)，避免覆盖 - 记得关 CGO：
CGO_ENABLED=0，否则 Linux 编译可能悄悄链接 libc，Alpine 容器里直接报not found
clean 不只是删 bin，还要清缓存和 modcache
只写 rm -rf bin 是假清理。Go 构建缓存存在 $GOCACHE（如 ~/.cache/go-build），模块源码缓存在 $GOMODCACHE，不清理会导致旧代码残留、测试结果误判。
- 完整 clean 应包含：
rm -rf bin && go clean -cache && go clean -modcache - 如果用了
go generate，还得加go generate -n预检或go generate ./...强制刷新 - 别信
go clean默认清一切——它默认只清当前包的 object 文件，对缓存无感 - 本地开发建议加
.PHONY: clean，防止和同名文件冲突
真正麻烦的不是写对一条命令，而是让不同人、不同机器、不同 CI 环境跑出来的二进制，连 ldflags 注入的 GitCommit 和 BUILD_TIME 都一致——这些细节一旦漏掉，线上排查就变成猜谜。
