cgo 默认启用，只需在 go 文件顶部用 // #include 注释块声明头文件，紧接空行后写 import "c"；import "c" 是 cgo 识别标志，非普通包导入，必须严格对齐无空行或错位。
如何在 Go 文件中正确启用 cgo 并声明 C 函数
必须在 Go 源文件顶部添加 // #include <xxx.h></xxx.h> 形式的注释块，并紧接一个空行，再写 import "C"。cgo 只识别这种紧邻的注释块，且不能有空行插入在注释和 import "C" 之间。
常见错误：把 #include 写成普通注释（如 // #include <stdio.h></stdio.h> 中多了一个斜杠）、或在注释块里用了 Go 风格的 /* */、或漏掉空行导致 import "C" 不被识别为 cgo 包导入。
示例：
// #include <math.h> // #include "mylib.h" <p>import "C"</p></math.h>
注意：import "C" 是固定写法，不是导入某个叫 C 的 Go 包，它由 cgo 工具在构建时动态生成绑定代码。
如何声明并调用 C 函数，特别是带指针或结构体参数的
C 函数名在 Go 中通过 C.funcname 访问，但所有参数和返回值必须是 Go 能直接映射的类型（如 C.int、C.double、*C.char），不能直接传 Go 的 string 或切片。
- 字符串需用
C.CString()转换，且必须手动C.free()释放，否则内存泄漏 - Go 切片转 C 数组需用
C.CBytes()，同样要C.free() - C 结构体在 Go 中表现为
C.struct_xxx，字段名与 C 端一致，但不可直接取地址传给 C 函数（需用&C.struct_xxx{...}） - 回调函数需用
C.callback+C.export配合，不能直接传 Go 函数值
示例（调用 C 的 sqrt）：
// #include <math.h> import "C" <p>result := C.sqrt(C.double(16.0)) // 注意类型显式转换</p></math.h>
为什么 go build 会报 “exec: 'gcc': executable not found” 或 “undefined reference”
cgo 默认依赖系统 GCC（或 clang）工具链。没有安装或未加入 PATH 会导致前者；后者通常因链接阶段缺失库或头文件路径不对。
解决方法：
- macOS：装 Xcode Command Line Tools（
xcode-select --install） - Linux：安装
build-essential（Debian/Ubuntu）或gcc+glibc-devel（CentOS/RHEL） - Windows：使用 TDM-GCC 或 MinGW-w64，并确保
gcc在 PATH 中 - 指定头文件路径：在
// #cgo CFLAGS:后加-I/path/to/headers - 指定链接库：在
// #cgo LDFLAGS:后加-L/path/to/lib -lmylib
注意：// #cgo 指令必须出现在 import "C" 之前的注释块内，且每行只能有一个指令。
如何避免 cgo 导致的 CGO_ENABLED=0 构建失败或交叉编译问题
默认开启 cgo，但若设 CGO_ENABLED=0，所有含 import "C" 的文件会编译失败。交叉编译（如 GOOS=linux go build）时，若目标平台无对应 C 工具链或库，也会失败。
关键点：
- 生产环境 Docker 多阶段构建中，常因 alpine 镜像缺 gcc/glibc 而失败，应改用
golang:alpine+apk add gcc musl-dev，或直接用golang:slim - 禁用 cgo 仅适用于纯 Go 项目；一旦用了 cgo，就无法用
CGO_ENABLED=0构建 - 某些 C 库（如 OpenSSL）在不同平台 ABI 差异大，建议优先用纯 Go 实现（如
crypto/tls）替代
真正麻烦的从来不是怎么写那一行 C.somefunc()，而是头文件路径错一层、C.free 忘一次、或者 CI 机器上少装了一个 dev 包——这些地方一卡就是半小时。
