Go cgo 文件必须放在什么构建条件下才会被识别

Go 项目里出现“明明有 .c 文件，为什么 go build 不识别”的问题时，先别急着改文件名。cgo 文件是否参与构建，取决于四层条件：当前构建是否启用 cgo、包含 import "C" 的 Go 文件是否被选中、C 源文件是否位于同一个包目录，以及 GOOS、GOARCH 和 go:build 约束是否全部满足。

最短判断是：cgo 启用时，含有 import "C" 的 Go 文件会被归入 CgoFiles；同一包目录下的 .c、.cc、.cpp 等文件才会进入对应的 C/C++ 文件列表。cgo 关闭、条件标签不匹配，或文件放在子目录时，文件就不会按你预期参与当前包构建。

先确认当前构建真的启用了 cgo

cgo 在本机原生构建中通常默认可用，但交叉编译时默认关闭；如果 CC 不存在或默认 C 编译器不在 PATH，Go 也可能无法建立可用的 cgo 构建环境。先把实际构建上下文打印出来：

# 查看目标系统、架构、cgo 开关和 C 编译器
go env CGO_ENABLED GOOS GOARCH CC

# 只在当前命令中打开 cgo；不要把临时排障值误写进全局配置
CGO_ENABLED=1 go env CGO_ENABLED

如果这里得到的是 CGO_ENABLED=0，含 import "C" 的文件不会进入本次构建。把它改成 1 也只是第一步：还要有能为目标平台工作的 C 编译器。尤其是 GOOS 或 GOARCH 与当前机器不同时，不能把“本机有 gcc”当成“目标 cgo 工具链已经准备好”。

把 import C 的 Go 文件和 C 源文件放在同一包目录

cgo 的入口是一个普通 Go 源文件中的特殊导入。导入前紧邻的注释会作为 C 预声明，因此 C 函数声明和 import "C" 必须保持在同一个 Go 文件里：

package bridge

// C 预声明会被 cgo 读取，并为后面的 C.hello 提供声明。
// #include 
// void hello(void);
import "C"

// CallHello 只负责从 Go 侧调用 C 函数。
func CallHello() {
	C.hello()
}

假设目录中还有 hello.c，它应与上面的 Go 文件属于同一个包目录，而不是放进 c/ 子目录后期待 Go 自动递归查找。cgo 会把同目录下的 .c 交给 C 编译器，把 .cc、.cpp、.cxx 交给 C++ 编译器；.h、.hh、.hpp 等头文件不会单独编译，但被修改时会触发该包重新构建。

检查 go:build 和文件名后缀是否把文件排除

文件放对目录后，还要看构建约束。go:build 是文件级条件，文件名也能表达条件，例如 source_windows.go 只在目标系统为 Windows 时参与构建。cgo 本身还会设置一个名为 cgo 的构建标签；含 import "C" 的文件等价于带有 cgo 条件。

//go:build cgo && linux

package bridge

// 这个文件只在 cgo 已启用且目标系统为 Linux 时参与构建。
import "C"

func linuxOnly() {
	// 这里放 Linux cgo 适配代码，避免被其他目标系统误选。
}

排查时按这个顺序看最省时间：

用 go list -json 直接查看文件分类

不要只看编辑器里的目录树。Go 的包描述已经把当前构建上下文下的文件分组了，用下面的命令可以直接观察：

# 输出当前目录的文件分类；把结果保存后可与另一组环境变量对比
go list -json .

# 只看最关键的四个字段，快速判断文件是被选中还是被忽略
go list -json . | jq '{CgoFiles, CFiles, CXXFiles, IgnoredGoFiles}'

重点看四类结果：CgoFiles 是导入了 C 的 Go 文件，CFiles 是 .c 文件，CXXFiles 是 C++ 文件，IgnoredGoFiles 则能提示某些 Go 文件为什么没有进入本次构建。若 CgoFiles 为空，优先回到 CGO_ENABLED、文件标签和导入写法；若 CgoFiles 有值而 CFiles 为空，检查 C 文件扩展名和是否位于当前包目录。

交叉编译时同时准备目标 C 编译器

交叉编译最容易误判：设置了 GOOS 和 GOARCH，并不代表 cgo 已经具备目标编译器。需要显式打开 cgo，并让 CC 指向可以生成目标平台对象文件的 C 交叉编译器：

# 示例：为 Linux amd64 目标启用 cgo，并指定目标 C 编译器
GOOS=linux GOARCH=amd64 CGO_ENABLED=1 \
CC=x86_64-linux-gnu-gcc \
go list -json .

# 确认包描述里已经出现 cgo 文件和 C 文件
GOOS=linux GOARCH=amd64 CGO_ENABLED=1 \
CC=x86_64-linux-gnu-gcc \
go build ./...

这里的 CC 名称只是示例，实际值取决于工具链；如果编译器不存在，错误会出现在 C 编译阶段，而不是“文件识别”阶段。先用 go list -json 确认文件已被选中，再处理头文件路径、链接库和目标 ABI，能把两个问题分开。

相关问题

只有 .c 文件、没有 import "C"，Go 会自动编译它吗？

不能把它当成普通 Go 文件使用。C 源文件属于包的非 Go 源文件分类，通常需要包中存在 cgo Go 文件来建立 cgo 构建上下文，且文件必须位于当前包目录并满足目标构建条件。

把 C 文件放到子目录，再在 Go 文件里写相对路径可以吗？

这不等同于让父包自动收集子目录源码。更清晰的做法是把同一个 cgo 包所需的 C 源文件放在包目录，或把子目录单独设计成另一个 Go 包并通过明确的包边界调用。

CGO_ENABLED=1 仍然构建失败，说明文件没被识别吗？

不一定。先看 go list -json 是否已经列出 CgoFiles 和 CFiles。若文件已列出，后续失败更可能是 C 编译器、头文件、库路径或链接配置问题。

相关依据

cgo 官方文档说明了特殊导入 C、同目录非 Go 源文件、CGO_ENABLED 与 cgo 构建约束之间的关系；go/build 文档则定义了 go:build、文件名约束以及 CgoFiles、CFiles 等字段。可直接查阅 cmd/cgo 与 go/build 的官方说明。