因为cgo将import "C"上方连续注释块视为C preamble并交由C编译器处理，中间插入空行、Go代码或非注释内容会截断preamble，导致C声明丢失而报undefined。
为什么 import "C" 必须紧挨着 C 声明块？
cgo 不是“解析 Go 文件里的 C 代码”，而是把 import "C" 上方连续的注释块（/* ... */ 或 // #include ...）当作 C 的 preamble 提交给 C 编译器。中间一旦插入空行、Go 代码或非注释内容，preamble 就被截断——C 函数声明丢失，C.some_func 直接报 undefined。
-
import "C"前必须是纯 C 声明/头文件包含，不能混 Go 变量、函数或空行 - 多个头文件要写在同一块注释里：
/* #include <stdio.h> #include "mylib.h" */，不能拆成两块 - 如果用了
// #cgo CFLAGS: -I./inc，它也得在import "C"前，且和 C 声明块之间不能有空行
调用自定义 C 函数时，.c 文件为啥不自动编译？
cgo 默认只处理注释块里的 C 代码，hello.c 这类独立文件根本不会被扫描。你看到的 undefined reference 错误，不是链接失败，是根本没编译那个 .c 文件。
- 最简单办法：把 C 实现直接塞进注释块里，比如
/* void say_hello() { puts("hi"); } */ - 想分离源码？得手动告诉 cgo 编译哪些 .c 文件：
// #cgo CFLAGS: -I./csrc+// #cgo LDFLAGS: ./csrc/hello.o（先用gcc -c hello.c -o hello.o编译好） - 别写
// #include "hello.c"——这不是头文件，C 编译器会报语法错
C 字符串传参后，什么时候该 free，什么时候不该？
C.CString 返回的是新分配的 *C.char，生命周期完全独立于 Go 字符串。不 free 就泄漏；free 早了就崩；存起来复用更危险。
- 传给 C 函数后立刻用
defer C.free(unsafe.Pointer(cstr))，这是最安全的模式 - 如果 C 函数内部做了
strdup或长期保存，你就不能 free——得看 C 侧文档，不是 Go 能决定的 - 绝对不要把
C.CString结果存在全局变量、map 或 channel 里：defer失效，谁来 free？ -
C.GoString返回的是 Go 堆副本，它不 touch 原始*C.char，哪怕你刚转完，原始指针仍需你自己C.free
链接静态库 libxxx.a 总提示符号找不到？
cgo 默认优先找动态库（.so/.dylib），即使当前目录放着 libxxx.a，它也视而不见——除非你明确指定路径和链接方式。
立即学习“go语言免费学习笔记（深入）”；
-
// #cgo LDFLAGS: -L./libs -lxxx中的-lxxx对应的是libxxx.a（Linux/macOS）或xxx.lib（Windows），不是xxx.a - 强制静态链接：加
-static-xxx（GCC）或直接写死路径：// #cgo LDFLAGS: ./libs/libxxx.a - macOS 上还得加
-Wl,-force_load，否则未直接引用的符号会被 strip：// #cgo LDFLAGS: -Wl,-force_load,./libs/libxxx.a - 确认架构匹配：x86_64 的
libxxx.a在 arm64 Go 程序里链接失败，连错误都不报，静默跳过
C 代码嵌入看似简单，但每个环节都卡在“约定”上：preamble 的边界、内存归属权、链接器行为、平台差异——这些不是 bug，是 cgo 的设计契约。漏掉一个，轻则编译不过，重则运行时踩内存。
