go generate 是轻量级命令触发器，非学习工具或构建系统；常见失效原因有格式错（注释顶格、无空格）、位置错（须在.go文件中）、路径错（仅扫描当前目录）。
直接说结论：go generate 不是语言学习工具，也不是工程化构建系统——它就是一个轻量、约定优先的命令触发器，用对了能省 80% 的模板代码，用错了连文件都生成不出来。
为什么 go generate 注释写了却没反应
最常见原因就三个：格式错、位置错、路径错。
- 注释必须顶格写，
//go:generate中间不能有空格，冒号后也不能有空格；写成// go:generate或//go: generate都会被完全忽略 - 必须写在
.go文件里，不能放在.md、.tmpl或.sh里；哪怕只有一行，也得塞进某个可编译的 Go 源文件中 -
go generate默认只扫描当前目录（不是脚本所在目录，也不是项目根目录），所以//go:generate ./gen.sh要求gen.sh和当前.go文件在同一目录下，且已chmod +x
go run vs 直接调二进制：哪种更适合自定义生成脚本
推荐用 go run，尤其当你还没 go install 过该工具时。
-
//go:generate go run ./tools/gen/main.go -model=User—— 依赖明确、版本可控、无需提前安装 - 直接调二进制（如
//go:generate gen-model -o user.go）要求该命令在$PATH中，CI 环境或新同事本地容易缺失，且不同机器上版本可能不一致 - 注意：
go run后面的路径是相对于执行go generate时的当前工作目录，不是相对于注释所在文件的位置；建议统一用项目根目录下的相对路径，比如./tools/gen
生成的文件为啥 go build 找不到
不是生成失败，而是“生成了但不在包里”。
立即学习“go语言免费学习笔记（深入）”；
- 输出路径必须落在当前 package 目录下，比如
./user_gen.go可以，../models/user_gen.go或/tmp/user_gen.go都不行 - 生成文件开头必须有
// Code generated by go generate; DO NOT EDIT.，否则某些 linter 会报错，Git 也可能误判为人工编辑 - 文件权限问题：如果生成目标已是只读（比如从 Git checkout 得来），
go generate默认不会覆盖，也不会报错，只会静默跳过——加-x参数运行看实际执行命令，再检查文件权限 - 构建约束冲突：生成文件顶部若含
//go:build ignore或其他 tag，且与当前构建条件不匹配，go build就直接忽略它
Shell 脚本里怎么安全传参给 go generate
go generate 不解析 shell 变量，只认预定义环境变量和字面量参数。
- 别写
//go:generate ./gen.sh $GOFILE——$GOFILE不会被展开，脚本收到的就是字面字符串"$GOFILE" - Go 1.19+ 支持
${GOFILE}、${GOPACKAGE}、${GODIR}，但低版本不兼容；稳妥做法是显式传参：//go:generate ./gen.sh --file main.go --package main - Python 脚本第一行必须是
#!/usr/bin/env python3，且脚本本身需chmod +x；否则在 macOS/Linux 上会报exec format error - 所有路径尽量用相对路径，避免
../../这类跨级写法——不同工作目录下执行go generate时，相对基准会变
真正难的不是写出能跑的生成逻辑，而是让每次 go generate 输出的文件内容稳定、路径确定、不因环境差异而失效。路径、权限、构建 tag、编码格式，漏掉一个，自动化就变成手动排查现场。
