go generate不会自动运行，必须手动执行且严格依赖环境与路径；CI/CD中遗漏会导致build失败，需在流水线显式调用并确保模块名、工作目录、生成路径一致。
模块化项目里，go generate 不会自动运行，也不参与构建流程——你必须手动执行它，且环境变量、工作目录、包路径稍有偏差，生成代码就 import 报错或文件写错位置。
go generate 命令必须手动触发，且只扫描当前包
它不是 go build 的一部分，不会在编译时悄悄执行。CI/CD 流水线里漏掉 go generate，后续 go build 就可能因缺少 zz_generated.go 或类型方法而失败。
- 默认只处理当前目录下的
.go文件，不递归子目录；要覆盖./internal/...，得显式写go generate ./...或用./...通配 -
//go:generate注释必须独占一行，//后**紧接**go:generate，中间不能有空格，也不能混用中文标点 - Windows 下若命令含
&&（如//go:generate go run gen.go && go fmt gen.go），cmd 会截断，应拆成两行注释，或封装为.bat/.sh
生成器脚本的路径和模块名必须与实际一致
常见报错：cannot find package "myproj/internal/util"，本质是生成器硬编码了 import 路径，但项目 module 名实际是 example.com/myproj。
- 别在生成器里写死
import "myproj/..."；应读取go.mod第一行module xxx，用它拼路径 - 输出文件路径推荐用相对当前包的路径，比如
types.gen.go，而非../../output/types.gen.go——后者在不同工作目录下会失效 - 生成器若调用
go list -m或runtime/debug.ReadBuildInfo()，需确保运行时GO111MODULE=on且当前目录在 module 根下
模块化结构下，generate 文件该放哪、怎么提交
生成代码是派生品，不是源码——它不该被当作“作者写的逻辑”来 review，但又必须可复现。
立即学习“go语言免费学习笔记（深入）”；
-
go:generate注释建议放在包主文件（如types.go）顶部，紧挨package xxx，方便一眼看到依赖哪些生成逻辑 - 生成器本身（如
tools/gen/main.go）应放在tools/或cmd/目录下，并在go.mod中声明为replace或通过go install确保 CI 可执行 - 生成文件（如
stringer_gen.go）应加入.gitignore；但要在 README 或 CONTRIBUTING.md 里写明：“修改枚举后需运行go generate ./...并提交新生成文件”——有些团队选择提交，前提是生成逻辑稳定、diff 可读
调试 generate 失败：从 -n 和 -x 开始
最常卡在“没反应”或“报错但看不到命令”，根本原因是命令没拼对，或环境不一致。
- 先跑
go generate -n ./...，看它实际打算执行什么命令——确认路径、参数、工具名是否正确 - 再跑
go generate -x ./...，观察真实 shell 输出；注意 Windows cmd 和 PowerShell 对引号、转义的处理差异 - 如果生成器是自定义
go run脚本，确保它入口函数末尾有os.Exit(0)或错误时返回非零码，否则go generate无法感知失败 - 检查
$GOFILE、$GOPACKAGE等环境变量是否被正确注入——它们只在//go:generate所在文件被处理时才设值
真正麻烦的从来不是写一条 //go:generate，而是让生成器在任意开发机、CI 节点、不同 Go 版本下都输出完全一致的代码——这意味着路径解析、模块名提取、格式化调用，全得收敛到最小可行假设上。
