go build报“exec: 'gcc' not found”是因为Go默认启用CGO，而net、os/user等标准库或依赖含C代码，需调用GCC编译；若系统未安装GCC或未配置PATH（如Alpine、最小化Linux、macOS M1/M2），就会触发该错误。
为什么 go build 在某些系统上直接报错“exec: 'gcc' not found”
Go 默认启用 CGO，只要标准库或依赖中含 cgo 代码（比如 net、os/user、crypto/x509），就会尝试调用系统 GCC 或 Clang 编译 C 部分。在容器、Alpine、最小化 Linux 发行版或某些 macOS M1/M2 环境下，GCC 根本没装，或者 pkg-config 缺失、头文件路径不对，导致编译中断。
典型错误信息：# runtime/cgo: exec: "gcc": executable file not found in $PATH 或 fatal error: sys/param.h: No such file or directory。
- 不是 Go 本身坏了，是 CGO 依赖的外部工具链缺失
- 即使你没写 C 代码，只要用了
net/http（它底层用 CGO 解析 DNS）就可能触发 - Alpine 镜像默认用
musl libc，而多数 Go 模块预编译的 cgo 依赖是面向glibc的，直接运行也会 panic
关闭 CGO 是最简单有效的绕过方式
设 CGO_ENABLED=0 后，Go 会跳过所有 CGO 调用，改用纯 Go 实现（例如 net 包用纯 Go DNS 解析器，os/user 用 /etc/passwd 解析）。虽然部分功能降级（如不支持 system CA bundle 自动加载、DNS 无法用 glibc 的 nsswitch），但绝大多数服务类应用完全可用。
- 构建时加环境变量：
CGO_ENABLED=0 go build -o myapp . - Dockerfile 中推荐写成两行，避免 shell 缓存问题：
ENV CGO_ENABLED=0<br>RUN go build -o /app/myapp .
- CI/CD 脚本里别只 export，要确保子 shell 继承：
CGO_ENABLED=0 go test ./...
保留 CGO 时必须配齐工具链和头文件
如果项目硬依赖 CGO（比如用了 sqlite3、openssl、zlib 等 C 库），就不能关 CGO，得补环境：
立即学习“go语言免费学习笔记（深入）”；
- Debian/Ubuntu：
apt-get update && apt-get install -y gcc libc6-dev pkg-config - Alpine：
apk add --no-cache gcc musl-dev pkgconfig（注意：用musl-dev，不是glibc） - macOS：
xcode-select --install+ 确保/usr/local/bin在 PATH（Homebrew 安装的 pkg-config 常在这里） - 交叉编译时，
CC和PKG_CONFIG_PATH必须指向目标平台工具链，否则会混用宿主机头文件
常见坑：pkg-config 找不到 openssl.pc？不是没装 openssl-dev，而是 pkg-config 没配置 PKG_CONFIG_PATH，尤其 Alpine 下需手动加 /usr/lib/pkgconfig:/usr/share/pkgconfig。
模块缓存和 vendor 目录可能藏旧的 cgo 构建残留
go mod download 或 go build 会在 $GOCACHE 存编译中间产物，其中包含 cgo 对象文件。如果之前用 CGO_ENABLED=1 构建过，再切到 CGO_ENABLED=0，有时仍会复用旧缓存，导致链接失败或符号未定义。
- 强制清缓存：
go clean -cache -modcache - vendor 里如果有
cgo相关的.c或.h文件，检查是否被误提交；go mod vendor默认不复制 C 头文件，除非模块显式声明了//go:cgo注释 - 用
go list -json -deps ./...查哪些依赖含CgoFiles字段，提前识别风险模块
真正麻烦的从来不是“怎么编译”，而是“为什么这次能编，上次不能”——环境变量、缓存、依赖版本、系统 libc 类型，四个变量一组合，就足够让构建结果不可重现。动手前先 echo $CGO_ENABLED 和 go env | grep -i cgo 看一眼，比盲试快得多。
