Makefile命令行必须用Tab而非空格；GOOS/GOARCH需在命令前设置；-ldflags参数必须用双引号包裹；make help要求##注释紧贴target末尾且无空格；.PHONY须声明所有伪目标。
Makefile 里用 Tab 还是空格？不搞清楚就报错
Make 要求命令行前必须是 Tab 字符，不是空格，也不是 4 个空格——哪怕你用编辑器显示为“缩进”，只要底层是空格，make 就会直接报错：Makefile:5: *** missing separator. Stop.。这个错误不提示“你用了空格”，只说“缺分隔符”，新手常卡在这里半小时。
解决办法很简单：
- 用 VS Code、GoLand 等现代编辑器时，打开“显示空白字符”，确认命令行前是
→（Tab）而非·（空格） - 在终端用
cat -A Makefile查看：Tab 显示为^I，空格就是普通 - 别依赖 IDE 自动缩进，手动按
Tab键输入命令行前缀
GOOS/GOARCH 交叉编译要设对，否则生成的二进制跑不了
想用 make build-linux 编出 Linux 用的程序，但本地是 macOS，结果生成的文件在 Linux 上报 cannot execute binary file: Exec format error——大概率是 GOOS 或 GOARCH 没生效。
常见写法陷阱：
立即学习“go语言免费学习笔记（深入）”；
-
GOOS=linux GOARCH=amd64 go build -o bin/app-linux .✅ 正确：环境变量作用于单条命令 -
export GOOS=linux; go build -o bin/app-linux .❌ 错误：export 只在当前 shell 生效，make 的每个命令是独立子 shell -
GOOS=linux GOARCH=arm64 go build -o bin/app-arm64 .⚠️ 注意：arm64 在 macOS 是darwin/arm64，Linux 是linux/arm64，别混用
建议统一用变量封装：build-linux: GOOS=linux GOARCH=amd64 $(MAKE) build，避免重复写死。
版本号注入到二进制里，-ldflags 写法容易漏引号
想让 ./bin/app --version 输出 git commit，代码里写了 var version string，但运行后还是空字符串——问题出在 -ldflags 的拼接上。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
正确写法必须带双引号包裹整个 flag 字符串：
-
-ldflags="-X main.version=$(VERSION)"✅ 可工作 -
-ldflags=-X main.version=$(VERSION)❌ shell 会把空格断开，go build 收到的是三个参数，-X后面没值 -
-ldflags="-X main.version=$(VERSION) -s -w"✅ 带 strip 和符号删除，推荐
注意：main.version 中的 main 是 Go 文件所在的包名，不是项目名；如果版本变量在 cmd/app/main.go 里，包名是 main，没问题；如果在 internal/version/version.go 且包名是 version，就得写成 -X version.version=$(VERSION)。
make help 不显示自定义目标？注释格式不对
写了 build: ## 编译主程序，但运行 make help 却看不到这行——因为 ## 必须紧跟在 target 行末尾，中间不能有空格，且不能换行。
正确示范：
-
build: ## 构建当前平台可执行文件✅ -
build: ## 构建当前平台可执行文件❌##前多了空格，help 不识别 -
build: \## 构建当前平台可执行文件❌ 换行后##不属于 target 行，被忽略
另外，.PHONY 必须声明所有非文件目标（比如 build、test），否则当项目目录下恰好有个叫 build 的文件时，make build 就会跳过执行。
实际项目里最常被忽略的，是 .PHONY 声明和 ## 注释位置——它们不报错，但会让自动化行为变得不可靠。
