go generate 是一个手动触发的代码生成指令，非构建流程组成部分，仅执行 //go:generate 注释指定的命令；它不自动运行、不解析 shell 变量、不保证执行顺序，需确保环境、路径和权限正确。
go generate 是什么，不是什么
它不是构建流程的一部分，不会自动运行；也不是代码生成器本身，只是个“触发器”。你写好生成逻辑（比如用 go:generate 注释标记），再手动执行 go generate 命令，它才去调用你指定的工具（如 stringer、mockgen 或自定义脚本）。
常见错误现象：go build 成功但运行时 panic，因为生成的文件没更新；或者 go generate 报错说找不到命令，其实是 PATH 里没配好依赖工具。
- 必须在
//go:generate注释所在包目录下执行命令，不能跨包或从项目根目录随便跑 - 注释必须顶格、无空格、以
//go:generate开头，后面紧跟一个 shell 命令（如//go:generate stringer -type=State） - 生成的文件默认不被
go mod tidy管理，得自己git add，否则 CI 可能因缺失文件失败
怎么写可靠的 //go:generate 注释
核心是让命令可复现、路径可预测、输出可预期。别写绝对路径，别依赖当前工作目录，更别用 $(pwd) 这类 shell 展开——go generate 不解析 shell 变量。
使用场景：为枚举生成字符串方法、为接口生成 mock、从 protobuf 生成 Go 结构体。
- 用
-o显式指定输出文件名，避免工具按约定乱放（例如//go:generate stringer -type=Mode -o mode_string.go） - 如果命令依赖其他文件（如
api.proto），确保它们和注释在同一目录，或用${GOFILE}、${GOOS}等预定义变量辅助定位（注意：这些变量仅在部分 go 工具链版本支持，Go 1.19+ 更稳） - 避免多个
go:generate行互相依赖顺序——它不保证执行顺序，也不做 DAG 调度
go generate 不生效的三个典型原因
不是语法写错了，就是环境或上下文没对上。最常卡在这三处：
-
//go:generate注释写在非 Go 源文件里（比如.md或.proto），它只扫描*.go文件 - 命令里用了别名（如
//go:generate gen-enum），但 shell 别名在go generate的子进程中不可见，得用完整路径或确保在$PATH中 - 生成目标文件已存在且是只读的（比如被 IDE 锁住或 git checkout 后权限设为 read-only），
go generate默认不会覆盖，会静默跳过或报错“permission denied”
和 go:embed、//go:build 并存时要注意什么
三者都是特殊注释，但处理时机完全不同：go:embed 在编译期由 go tool compile 解析，//go:build 影响文件是否参与编译，而 go:generate 完全在用户手动调用时运行，不参与任何构建阶段。
容易踩的坑：有人想用 go:generate 生成一个 embed 所需的文件，结果发现 go run 时 embed 还没生效——因为 go generate 没提前跑，或者生成的文件没被 go:embed 正确匹配（比如路径大小写、通配符没对上）。
-
go:embed匹配的是生成后存在的文件，不是生成命令里的路径表达式 - 若生成逻辑依赖构建标签（如只在
linux下生成某文件），记得在//go:generate上方加对应//go:build linux，否则它可能在所有平台都尝试执行，导致失败 - 不要指望
go generate能替代go:embed的功能——它不提供编译期资源绑定能力，只是帮你把文件“造出来”
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
