Go generate 在 CI 中找不到命令怎么办

Go generate 在 CI 中提示“找不到命令”，通常不是 go generate 没有读取到指令，而是指令里的生成器可执行文件不在当前 job 的 PATH，或者生成器与仓库的相对路径是在错误的目录下解释。排查时要把“指令是否被识别”“命令从哪里查找”“生成器在哪个目录运行”分开看。

官方资料：https://go.dev/blog/generate

命令文档：https://go.dev/cmd/go/

最短修复路径是：先在 CI 中打印 pwd 和 PATH，再用 command -v 生成器 确认工具可见，最后在同一个 job 中安装工具、追加安装目录并执行 go generate ./...。如果指令使用仓库内的 go run ./cmd/gen，还要确认 CI 已经进入正确的 checkout 目录。

先确认 go:generate 指令真的被识别

Go 官方文档规定，指令必须是行首的 //go:generate，斜杠后不能有空格。它不是普通的 Go 注释说明：go generate 会扫描源文件中的这类行，并按包逐个处理；它也不会被 go build 或 go test 自动触发。

package schema

// 生成器入口放在仓库内，便于 CI 使用当前模块的依赖。
//go:generate go run ./cmd/schema-gen -input schema.yaml -output generated.go

// Schema 是业务代码使用的最小配置结构。
type Schema struct {
	Name string
}

这条指令有两个容易忽略的边界：第一，//go:generate 必须从行首开始；第二，go generate 只处理命令行指定的包或文件。为了覆盖模块中的多个包，通常从模块根目录调用 go generate ./...，而不是只在一个目录执行。

如果 CI 日志里完全没有出现生成器命令，先用 go generate -n ./... 查看将要执行的命令。这个检查只确认指令发现和包范围，不代表生成器已经成功运行。

区分包源目录和 CI 当前工作目录

一个常见误判是把 CI 脚本中的当前目录当成生成器的运行目录。Go 文档说明，生成器会在包的源目录中运行；而 CI 脚本中的 pwd 决定了 go generate ./... 先从哪里解析包模式。仓库被 checkout 到子目录、脚本先进入了缓存目录，都会让相对路径表现不同。

例如，指令写成 go run ./cmd/schema-gen 时，cmd/schema-gen 应当是相对于包含该指令的包源目录可定位的路径。如果指令写成 schema-gen，它就依赖 CI 环境的 PATH，与仓库是否 checkout 成功是两件事。

用 PATH 检查找不到命令的直接原因

Go 的 go generate 要求指令中的生成器要么能在 shell 的 PATH 中找到，要么使用完整路径或文件内命令别名。CI 中最有价值的诊断不是重复执行，而是在同一个 job、同一个 shell 中打印工具位置：

#!/usr/bin/env bash
set -eu

# 先确认脚本运行在哪个 checkout 目录。
printf 'workdir=%s\n' "$PWD"
printf 'PATH=%s\n' "$PATH"

# 裸命令必须能被当前 shell 找到；找不到时立刻给出明确错误。
command -v schema-gen || {
  printf 'schema-gen 不在 PATH 中\n' >&2
  exit 1
}

# 记录 Go 工具链使用的安装目录，便于和 PATH 对照。
go env GOROOT GOPATH GOBIN

# 确认工具可见后，再让 go generate 扫描模块中的包。
go generate ./...

如果 command -v 失败，先不要修改 go:generate 指令。应检查工具安装步骤是否在当前 job 执行、安装目录是否是另一个 shell 的临时变量，以及 PATH 追加是否发生在 go generate 之前。

固定工具安装目录和 PATH

本地环境常常因为开发者已经安装过工具而“自然成功”，CI 则是干净环境。更稳定的做法是给生成器固定版本，并把 Go 的可执行文件目录显式加入后续命令的 PATH。go install 安装命令的默认目录受 GOBIN 或 GOPATH/bin 影响，因此不能只假设某个机器路径一定存在。

# 用真实生成器模块和版本替换示例路径，避免依赖 CI 镜像预装工具。
go install example.com/acme/schema-gen@v1.2.3

# 读取 Go 计算出的安装目录，并让后续命令看到它。
tool_bin="$(go env GOBIN)"
if [ -z "$tool_bin" ]; then
  tool_bin="$(go env GOPATH)/bin"
fi
export PATH="$tool_bin:$PATH"

# PATH 生效后再检查命令，避免把安装成功误当成可执行。
command -v schema-gen
go generate ./...

如果 CI 平台把每个步骤放在不同 shell 中，单纯 export PATH=... 可能只对当前步骤有效。此时要使用平台提供的 job 级环境变量、环境文件或在同一个脚本中连续完成安装与生成；不要把“上一段脚本打印过 PATH”当成下一步仍然继承的证据。

把排查点放进 CI 工作流

一个可复用的流水线顺序是：准备 Go 工具链，确认 checkout 目录，安装固定版本的生成器，追加安装目录，检查命令位置，最后运行生成。下面用通用 YAML 表达依赖关系，变量名需要按实际 CI 平台替换：

steps:
  - name: generate sources
    shell: bash
    run: |
      set -eu
      # CI_PROJECT_DIR 代表平台提供的仓库目录变量。
      cd "$CI_PROJECT_DIR"
      test -f go.mod

      # 安装和执行放在同一个 job，避免 PATH 只存在于前一个 shell。
      go install example.com/acme/schema-gen@v1.2.3
      tool_bin="$(go env GOBIN)"
      if [ -z "$tool_bin" ]; then tool_bin="$(go env GOPATH)/bin"; fi
      export PATH="$tool_bin:$PATH"

      # 先检查工具，再扫描包并确认生成文件存在。
      command -v schema-gen
      go generate ./...
      test -f path/to/generated.go

如果仓库约定生成文件必须提交，CI 可以把 git diff --exit-code 作为后续门禁；如果生成文件只在构建阶段产生，则应把它交给后续构建步骤，而不要让生成步骤假设工作区已有产物。这里的关键仍是顺序和边界，不是某一个 CI 平台的语法。

常见误区与最后的速查表

• 把 go generate 当成 go build 的隐含步骤：它必须显式调用，构建不会替你生成源文件。
• 只安装工具不更新 PATH：安装成功只说明文件写入某个目录，不说明当前 shell 能通过裸命令找到它。
• 只在模块根目录检查路径：生成器实际在包源目录运行，指令中的相对路径要按包目录理解。
• 把工具安装和生成拆到不同 shell：环境变量可能没有跨步骤继承，应使用 CI 的持久环境机制或合并脚本。

常见追问

为什么本地直接运行 go generate 没问题，CI 却找不到命令？

本地 PATH 可能已经包含个人 Go 工具目录，而 CI 是干净环境；另外 CI 的 checkout 目录和本地模块根目录也可能不同。把 pwd、command -v 和 go env GOBIN GOPATH 放进同一个 job，通常能快速区分这两类原因。

把生成器写成绝对路径是不是最稳？

绝对路径能绕过 PATH，但会把机器目录写进源码，不利于跨开发机和 CI 复用。更通用的方式是固定版本安装，并在 job 内显式维护 PATH；只有生成器确实由固定系统路径提供时才考虑绝对路径。

go run ./cmd/schema-gen 还需要把生成器安装到 PATH 吗？

不需要依赖一个同名裸命令，但仍需要正确的模块上下文、包源目录和依赖下载条件。它适合仓库内自有生成器；第三方命令行工具则更适合固定版本安装并显式加入 PATH。

本文依据 Go 官方生成命令说明、生成器源码文档和 Go 官方博客整理：https://go.dev/cmd/go/、https://go.dev/src/cmd/go/internal/generate/generate.go、https://go.dev/blog/generate。具体 CI 平台的环境继承规则仍应以该平台文档为准。