Go 编译报 undefined: C 时怎么确认是不是漏了 cgo 文件

遇到 undefined: C 时，先不要把它当成普通的 C 函数链接错误。这个报错通常说明当前 Go 源文件没有获得 cgo 提供的伪包 C；如果错误是 undefined: C.xxx，才继续检查 preamble、头文件声明和 C 文件是否进入了同一个包。最快的排查顺序是：看报错文件的 import "C"，再看 CGO_ENABLED 与构建约束，最后用 go list 确认文件清单。

核心判断：undefined: C 优先查“这份 Go 文件有没有被 cgo 处理”，不要先去改链接参数；只有 C.xxx 已经被识别后，才需要追 C 声明或库链接。

先判断编译器到底有没有看到 cgo 文件

把错误拆成两层，定位会快很多。undefined: C 指向的是伪包标识符本身，常见原因是当前文件缺少特殊导入，或者包含它的文件因为 cgo 开关、操作系统、架构或 build tag 被排除。undefined: C.add 则表示 C 已被识别，但名为 add 的声明没有从 preamble 或头文件中生成。

先在报错文件中确认导入形态。它必须是特殊的伪包导入，而不是把 C 当成普通模块名：

package bridge

// #include 
// static int32_t add_one(int32_t value) { return value + 1; }
import "C"

func AddOne(value int32) int32 {
	// 通过 C 伪包访问 preamble 中的 C 声明。
	return int32(C.add_one(C.int32_t(value)))
}

这里的注释就是 cgo 的 preamble，必须紧邻 import "C"。如果把这段注释放在别的函数上方、拆到另一个 Go 文件，或者只留下 import "C" 却没有声明，就会从“伪包识别”继续走向“C 名称不存在”的另一类错误。

用 go env 和 go list 确认文件是否进入构建

在包目录执行下面的检查。它只读取构建器的选择结果，不需要先清理缓存：

# 查看目标平台、cgo 开关和实际使用的 C 编译器
go env CGO_ENABLED GOOS GOARCH CC

# 输出当前包的文件选择，重点看 CgoFiles 和 IgnoredGoFiles
go list -e -json .

# 需要更完整的构建线索时，再显示 go build 传给工具链的参数
go build -x ./...

在 JSON 中，含有 import "C" 的文件通常应出现在 CgoFiles。如果它落在 IgnoredGoFiles，重点检查文件名后缀、//go:build 表达式和当前的 GOOS/GOARCH。如果 CGO_ENABLED 为 0，先不要用“加一个 C 文件”解决，因为被排除的 Go 文件本身就不会为当前目标生成 cgo 代码。

用最小目录结构恢复可重复构建

确认文件选择后，把 C 相关输入收敛到同一个包目录。cgo 会寻找该目录中的 .c、.s 等非 Go 文件；头文件不会单独编译，但会参与重新构建判断。一个容易复查的布局如下：

bridge/
├── bridge.go      # 包声明、preamble、Go 到 C 的类型转换
└── native.c       # 与 bridge.go 同包目录的 C 实现

当声明放在 native.h 时，在 preamble 中写 #include "native.h"，不要把头文件放到包外再期待构建器自动追踪。为了区分“代码选择”与“工具链”两种问题，可以显式重试：

# 先在支持 cgo 的目标上打开 cgo，并指定编译器
CGO_ENABLED=1 CC=clang go build ./...

# 交叉编译必须改成目标平台可用的 C 交叉编译器
CGO_ENABLED=1 GOOS=linux GOARCH=arm64 CC=aarch64-linux-gnu-gcc go build ./...

如果显式设置后 undefined: C 仍然存在，回到 go list -e -json . 看文件是否仍被忽略；如果错误变成 C.add 或头文件找不到，说明 cgo 已经接管了文件，下一步才是修声明和编译参数。

回滚路径和复盘清单

生产构建不能依赖“本机恰好装过 gcc”。发布前至少保存 go env CGO_ENABLED GOOS GOARCH CC 和 go list -e -json . 中的文件选择结果。若目标环境不允许安装 C 工具链，回滚到纯 Go 实现或把 cgo 封装隔离到带明确构建约束的文件中；不要只删掉 import "C"，否则业务代码可能留下无法解释的类型或能力缺口。

复盘时按“文件是否入选、preamble 是否声明、C 编译器是否匹配、目标平台是否一致”四项记录。这样下一次再出现同样报错，可以直接判断是源码回归、构建环境漂移，还是交叉编译配置变化。

常见问题

只安装 gcc 就能修复 undefined: C 吗？

不一定。gcc 主要解决 C 编译器不可用；undefined: C 更常见的根因是 Go 文件没有被 cgo 处理或缺少 import "C"。

为什么本地能编译，交叉编译就失败？

cgo 在交叉编译时默认更容易被关闭，而且目标平台需要匹配的 C 交叉编译器。分别查看 CGO_ENABLED、GOOS/GOARCH 与 CC，不要只比较 Go 版本。

改了 native.c 后为什么感觉没有重新编译？

先确认它位于包目录且在 go list 的 cgo 输入范围内；如果改动的是包外 C 库，Go 构建缓存未必能感知，应该按项目构建约定显式触发重建。

参考：cmd/cgo 官方文档、cmd/go 官方文档、Go 源码安装说明。