go generate 未按预期执行工具命令的工作目录排查

如果 go generate 明明找到了指令，却提示工具找不到、输入文件为空，或者生成文件出现在意料之外的目录，先不要改工具参数。最容易被忽略的原因是：生成器默认在包含 //go:generate 指令的 Go 包源目录运行，而不是在你敲下命令时所在的终端目录运行。

官方地址：https://pkg.go.dev/cmd/go

先确认 go generate 的工作目录

go generate 是显式执行器：它扫描已有 Go 文件中的 //go:generate command args... 指令，然后逐个运行命令。官方文档说明，生成器会在包的源目录运行；如果命令行传入的是同一目录下的 Go 文件，这些文件会被当成一个包处理。

因此，下面的指令读取的是 schema.json 相对于 model.go 所在包目录的位置，而不是相对于父目录或当前 shell 的位置：

package model

//go:generate go run ../internal/gen/main.go -input schema.json -output zz_generated.go

// 该文件只放生成指令；相对路径以本包源目录为起点理解。
type User struct {
	Name string
}

可以把问题先分成两类：报错里出现“executable file not found”时，优先看生成器是否在 PATH 中；报错里出现输入文件或输出目录不存在时，优先看指令文件所在包目录下的相对路径。两类问题看起来都像“命令没按预期执行”，但处理入口不同。

用最小指令区分命令路径和输入路径

先用 -n 只打印将执行的命令，不真正运行生成器；再用 -x 在执行时打印命令。两者都适合确认参数有没有被 shell 引号、环境变量或相对目录影响。

# 进入模块目录，先只查看 go generate 将执行的指令
cd ./example
go generate -n ./...

# 需要观察实际执行顺序时，再打开命令回显
go generate -x ./...

如果 -n 打出的第一段命令本身就找不到工具，修复工具安装位置或改用明确的可执行路径；如果命令看起来正确但输入文件为空，继续检查生成器收到的相对路径。不要先把所有路径都改成绝对路径，因为那会掩盖项目结构问题。

用环境变量确认指令上下文

Go 在执行生成指令时会设置一组上下文变量。排查时可以写一个临时生成器，把当前文件名、指令行号、包名和操作系统打印出来。下面的例子只负责观察上下文，不修改项目文件：

package main

import (
	"fmt"
	"os"
)

func main() {
	// 这些变量由 go generate 注入，用来确认指令来自哪个源文件和包。
	keys := []string{"GOFILE", "GOLINE", "GOPACKAGE", "GOOS", "GOARCH"}
	for _, key := range keys {
		// 没有变量时保留空值，避免把缺失上下文误判成固定目录。
		fmt.Printf("%s=%q\n", key, os.Getenv(key))
	}
	// 当前工作目录用于验证相对路径的真实起点。
	wd, err := os.Getwd()
	if err != nil {
		// 诊断程序遇到目录读取错误时立即返回非零状态。
		panic(err)
	}
	fmt.Printf("working directory=%s\n", wd)
}

把它挂到包中的 //go:generate go run ../internal/gen/context.go 后运行，输出中的 working directory 应该落在包含指令的包源目录。GOFILE 和 GOPACKAGE 则能确认到底是哪一个文件、哪个包触发了命令。

处理模块根目录与跨目录生成

当生成器需要读取模块根目录的配置文件时，不要假设包源目录就是模块根目录。可以在生成器中明确接收一个配置路径，也可以先根据项目约定定位模块根目录，再计算输入和输出路径。关键是让“从哪里执行”和“文件放在哪里”成为显式约定。

package tools

//go:generate go run ../internal/gen/main.go -config ../../generator.yaml -output generated/zz_config.go

// 配置路径相对于 tools 包目录，输出目录也固定在当前包内。
type Marker struct{}

如果命令需要执行多个子工具，可以用 -command 给多词命令建立别名；如果只想处理部分指令，可使用 -run 选择匹配的指令文本。无论使用哪种方式，路径的起点仍然要按指令所在包目录设计。

package model

//go:generate -command gen go run ../internal/gen/main.go
// 通过别名保持参数区分清楚，避免把多词命令重复写在每条指令里。
//go:generate gen -input schema.json -output zz_schema.go

建立可重复的排查和收尾习惯

修正路径后，建议按固定顺序重跑：先用 go generate -n 确认指令文本，再用 go generate -x 观察实际执行，最后查看版本控制差异，确认生成文件写入了预期目录。生成器返回非零状态时，同一包后面的指令不会继续处理，所以第一处错误通常最值得先看。

# 先确认指令，再执行全部生成步骤
go generate -n ./...
go generate -x ./...

# 只检查生成结果是否落在预期位置，不把日志当成源文件提交
git diff --stat
git status --short

排查时还要注意三点：第一，go generate 不会被 go build 或 go test 自动触发；第二，指令是按文件名和出现顺序逐个处理的，前一个生成器失败会影响同一包的后续指令；第三，生成器如果依赖外部环境，应该在项目文档中写清工具版本、输入文件位置和输出目录。

常见问题

为什么我在项目根目录运行，生成器却找不到相对文件？

因为相对路径通常按包含 //go:generate 的包源目录解释。先用 go generate -n 和临时上下文输出确认真实工作目录，再调整输入路径。

命令在我的终端能运行，go generate 却提示找不到？

优先比较两次运行的 PATH 和命令写法。生成器必须能通过 PATH、绝对路径或 -command 别名找到，终端里临时配置的 PATH 不一定会出现在自动化环境中。

怎样避免生成文件写到错误目录？

在指令中明确输出目录，并让生成器打印或记录当前工作目录；跨目录读取配置时不要依赖调用者位置，必要时传入明确的配置路径。