规范Go项目Makefile应定义build、test、fmt、vet、clean及可选run六个核心target；需用变量封装LDFLAGS注入版本与时间戳，参数化支持多平台交叉编译，test默认启用-race和-short，clean须覆盖bin/、coverage.out、.go-coverage/及vendor/。

Makefile 里该定义哪些核心 target 才算规范

Go 项目不需要 Makefile 也能构建，但加了 Makefile 是为了统一本地开发、CI 和协作流程。真正需要的 target 很少：build、test、fmt、vet、clean，最多再加个 run。别一上来就写 docker-build 或 deploy——那些属于部署层，不该污染构建规范。

常见错误是把 Go 的 go build 直接裸写进 recipe，忽略 -ldflags 注入版本或时间戳，导致二进制无法溯源。正确做法是用变量封装：

VERSION ?= $(shell git describe --tags --always --dirty)
LDFLAGS = -ldflags "-X main.version=$(VERSION) -X main.buildTime=$(shell date -u +%Y-%m-%dT%H:%M:%SZ)"
build:
go build $(LDFLAGS) -o bin/app ./cmd/app

GOOS/GOARCH 多平台交叉编译怎么写进 Makefile

硬编码 GOOS=linux GOARCH=amd64 go build 不可维护。应该用参数化 target，避免重复写多遍命令：

• make build-linux-amd64、make build-darwin-arm64 这类 target 要共用同一套构建逻辑
• 用 MAKECMDGOALS 解析目标名太脆弱；推荐显式传参：make build GOOS=windows GOARCH=386
• 注意 CGO_ENABLED=0 必须显式关掉，否则跨平台时可能因本地 cgo 环境失败

示例：

build:
    CGO_ENABLED=0 GOOS=$(GOOS) GOARCH=$(GOARCH) go build $(LDFLAGS) -o bin/app-$(GOOS)-$(GOARCH) ./cmd/app
默认构建本机平台
.PHONY: build-local
build-local: GOOS := $(shell go env GOOS)
build-local: GOARCH := $(shell go env GOARCH)
build-local: build

为什么 test target 要加 -race 且默认不跑集成测试

Go 的 go test 默认只跑单元测试（当前包下 *_test.go 中非 integration 标签的测试）。集成测试通常依赖外部服务（DB、HTTP 服务），不能放进 make t

• make test 应等价于 go test -race -short ./...：-race 检查竞态，-short 让测试主动跳过耗时逻辑（靠 if testing.Short() { t.Skip() }）
• 集成测试建议单独 target：make test-integration DB_URL=postgres://...，且必须显式传依赖配置
• 别在 Makefile 里写 go test ./... -timeout 30s —— timeout 是 per-package，不是全局，容易误判

clean target 容易漏掉的三个路径

clean 看似简单，但 Go 工作流中实际生成物不止 bin/：

• bin/：显式构建输出，必删
• ./.go-coverage/ 或 coverage.out：go test -coverprofile 生成，CI 上传覆盖率前要清理旧文件
• $(GOPATH)/pkg/mod/cache/download/？不用动——那是模块缓存，不是项目产物；但 $(PWD)/vendor/ 如果用了 vendor，就得加到 clean 里

稳妥写法：

clean:
    rm -rf bin/
    rm -f coverage.out
    rm -f *.out
    rm -rf .go-coverage/
ifeq ($(wildcard vendor/), vendor/)
    rm -rf vendor/
endif

真正难的是团队里有人手动 go install 到 $(GOBIN)，那不属于项目目录，Makefile 不该管——规范文档里写清楚即可。