import "C" 必须紧贴注释块且中间无空行，否则导致 undefined reference 或 cgo 错误；C 头文件路径、链接库、内存管理（C.CString/C.free）、Go 函数导出（//export）、交叉编译路径匹配等均需严格遵循 cgo 规则。
Go 调用 C 函数时，import "C" 必须紧贴注释块且中间不能有空行
这是最常导致 undefined reference to 'xxx' 或 cgo: C source files not allowed 的原因。Go 的 cgo 机制依赖紧邻的注释块（// #include <stdio.h> 等）来识别 C 代码边界，import "C" 不是普通导入语句，而是 cgo 的解析锚点。
实操要点：
-
import "C"前只能有纯注释（以//或/* */包裹），不能有任何 Go 代码、空行、甚至不可见 Unicode 字符 - C 头文件路径若为系统路径（如
<stdlib.h>），直接写；若是本地头文件（如"mylib.h"），需确保-I路径已通过// #cgo CFLAGS: -I./include告知 cgo - 如果 C 函数声明在头文件中但链接时报
undefined reference，大概率是没提供对应静态/动态库——得用// #cgo LDFLAGS: -L./lib -lmylib
C.CString 和 C.GoString 的内存生命周期必须手动管理
Go 字符串是只读且带长度的，C 字符串是以 \0 结尾的裸指针。两者转换不自动关联 GC，搞错就会出现崩溃或内存泄漏。
典型错误场景：
立即学习“go语言免费学习笔记（深入）”；
- 用
C.CString("hello")传给 C 函数后，忘记调用C.free()释放——C 分配的内存不会被 Go GC 回收 - 把 C 函数返回的
char*直接传给C.GoString()，但该指针指向的是 C 栈上临时变量（比如函数内char buf[64]; return buf;）——Go 字符串会拷贝此时已失效的内容 - 重复对同一
*C.char调用C.GoString()没问题，但重复C.free()会导致 double-free 崩溃
安全做法：C 分配的内存（C.CString、C.malloc）必须配对 C.free；C 返回的堆内存（如 strdup）也要由 Go 侧 C.free；栈内存绝不转成 Go 字符串。
导出 Go 函数供 C 调用时，签名必须是 C 兼容类型，且加 //export 注释
Go 函数默认不可被 C 链接。要让 C 代码能回调 Go，必须显式导出，且参数/返回值只能是 C 基本类型（C.int、C.size_t、*C.char 等），不能是 Go 的 string、slice、struct。
关键约束：
-
//export my_callback必须紧挨着函数定义前，且中间无空行；函数名在 C 侧就是my_callback，不是MyCallback - 导出函数不能有 Go runtime 依赖（比如不能调用
fmt.Println），否则可能在 C 线程中触发 panic 或死锁；建议只做简单数据转发，复杂逻辑扔回 Go goroutine - 若需传 slice 给 C，得拆成
*C.void+C.size_t长度；若需从 C 接收数组，用(*C.T)(unsafe.Pointer(&slice[0]))转，但务必确认 slice 已固定（如用runtime.Pinner或分配在 C 堆）
交叉编译时，// #cgo CFLAGS/LDFLAGS 中的路径和库名必须匹配目标平台
本地开发能跑通，一到 GOOS=linux GOARCH=arm64 go build 就报 cannot find -lxxx，基本是 cgo 指令仍指向宿主机的头文件和库。
解决思路：
- 不要硬编码
// #cgo CFLAGS: -I/usr/include——改用相对路径或环境变量（如// #cgo CFLAGS: -I${SRCDIR}/cdeps/include） - 交叉编译时，C 工具链（
CC_FOR_TARGET）、头文件、库文件都得是目标平台的版本；推荐用docker buildx或预装对应 sysroot 的容器 - 检查是否误用了
pkg-config：它默认查宿主机路径；应设PKG_CONFIG_SYSROOT_DIR和PKG_CONFIG_PATH指向目标平台的.pc文件目录
真正麻烦的从来不是语法，而是 C 构建生态和 Go 构建模型之间的隐式耦合——一个没对齐的路径、一个没 pin 住的内存、一次没配对的 free，都会让程序在某个特定平台或负载下突然失效。
