Go cgo 指针规则导致 panic 的边界定位

cgo 调用突然出现指针规则 panic 时，真正要定位的不是 unsafe.Pointer 写法本身，而是两条边界：传给 C 的地址指向哪一类内存，这块内存里是否还含有未固定的 Go 指针；以及 C 会不会在当前调用返回后继续保存或使用这个地址。

Go cgo 指针规则官方文档：https://pkg.go.dev/cmd/cgo#hdr-Passing_pointers

同步调用且 C 不保存地址时，可以短暂传入指向“无 Go 指针数据”的 Go 指针，例如非空 []byte 的底层字节区。只要 C 要跨调用保留状态，优先改用 runtime/cgo.Handle 或复制到 C 内存；只有确实需要长期保留 Go 对象地址，并能完整管理所有可达指针时，才考虑 runtime.Pinner。

先用两个问题框定 panic

一个常见现场是把 Go 结构体整体转成 unsafe.Pointer 交给 C。结构体看起来只是一个地址，但其中的切片字段包含指向 Go 堆的指针。Cgo 在运行时检查到“Go 指针指向的内存里还有未固定的 Go 指针”时，就可能直接 panic。

package bridge

/*
#include 
static void consume(void *p, size_t n) {
    // 示例函数只在本次调用期间读取，不保存 p
    (void)p;
    (void)n;
}
*/
import "C"

import "unsafe"

type Packet struct {
    Data []byte // slice 头部包含指向 Go backing array 的指针
}

func bad(packet *Packet) {
    // 错误边界：把含 Go 指针的整个结构体暴露给 C
    C.consume(unsafe.Pointer(packet), C.size_t(len(packet.Data)))
}

排查时先回答两个问题。第一，地址来自 Go 的 new、局部变量、切片 backing array，还是来自 C.malloc？内存归属是动态属性，与指针的静态类型无关。第二，C 只在函数体内读写，还是把地址存进全局变量、对象字段、异步任务或回调上下文？后者会把生命周期延长到 cgo 调用之外。

最小修复：只借出真正的数据区

如果 C 函数只是同步读取字节，不需要结构体元数据，也不保存地址，就不要传整个 Packet。改成传底层字节区的首地址和长度，Go 会在这次 cgo 调用期间隐式固定该内存。因为 byte 不包含 Go 指针，这个区域满足规则。

func consumeBytes(buf []byte) {
    if len(buf) == 0 {
        // 空切片没有可取地址的数据，按接口约定直接返回
        return
    }

    // 只把 backing array 的字节区借给同步 C 调用
    C.consume(unsafe.Pointer(unsafe.SliceData(buf)), C.size_t(len(buf)))

    // 明确保持切片活到调用之后；它不能替代固定或所有权管理
    runtime.KeepAlive(buf)
}

这段代码的安全前提很窄：C 不修改越界、不在返回后使用 p、不把地址转交给其他线程。runtime.KeepAlive 只说明 Go 值在某个程序点之前仍然存活，它不会把对象变成 C 内存，也不会允许 C 长期保存地址。

为什么换成 unsafe.Pointer 仍然会 panic

unsafe.Pointer 只是绕过静态类型系统，不会改变垃圾回收器对内存的判断。接口、channel、map、函数值在非零状态下总是含有 Go 指针；数组、切片、字符串和结构体是否含指针取决于内部类型与构造方式。

对结构体字段取地址时，规则关注的是该字段占用的内存，而不是整个结构体；但对数组元素或切片元素取地址时，规则关注整个数组或整个 backing array。因此，&packet.Count 可能只涉及一个无指针整数，&packet.Data[0] 则涉及整块 backing array。若元素类型本身含指针，依然不能因为只取第一个元素就绕过规则。

C 要保留状态时，优先从三种方案里选

当 C 库要在注册函数返回后继续使用上下文，最稳妥的方案不是继续包装 unsafe.Pointer，而是按数据用途选择句柄、C 内存或固定的 Go 对象。

回调上下文：用 runtime/cgo.Handle

cgo.Handle 是可表示任意 Go 值的整数句柄。C 保存整数，回调 Go 时再还原，不需要让 C 直接持有 Go 堆地址。句柄会占用资源，只有在 C 明确不再保留它之后才能调用 Delete。

package bridge

/*
#include 
extern void goCallback(uintptr_t handle);

static void invoke(uintptr_t handle) {
    // C 侧只传递整数句柄，不保存 Go 指针
    goCallback(handle);
}
*/
import "C"

import "runtime/cgo"

//export goCallback
func goCallback(raw C.uintptr_t) {
    handle := cgo.Handle(raw)
    message := handle.Value().(string)
    println(message)
}

func callWithHandle(message string) {
    handle := cgo.NewHandle(message)
    // C 返回且不再保存句柄后才释放
    defer handle.Delete()
    C.invoke(C.uintptr_t(handle))
}

长期缓冲区：复制到 C 内存

如果 C 需要长期保存原始字节，复制到 C 堆通常比固定 Go 内存简单。C.CBytes 会分配并复制，之后必须在 C 完成使用后调用 C.free。

/*
#include 
static void store_bytes(void *p, size_t n) {
    // 实际库会保存该 C 内存地址，直到 release_bytes 被调用
    (void)p;
    (void)n;
}
static void release_bytes(void *p) {
    free(p);
}
*/
import "C"

import "unsafe"

func storeCopy(buf []byte) unsafe.Pointer {
    // C.CBytes 把内容复制到 C 堆，空切片也由调用方统一处理
    ptr := C.CBytes(buf)
    C.store_bytes(ptr, C.size_t(len(buf)))
    return ptr
}

func releaseCopy(ptr unsafe.Pointer) {
    // 必须等 C 不再读取后再释放，不能在注册函数返回时提前 defer
    C.release_bytes(ptr)
}

必须保留 Go 地址：谨慎使用 runtime.Pinner

runtime.Pinner 可以让 C 在 cgo 调用返回后继续持有某个 Go 对象的地址，但它不是“固定整个对象图”。如果被固定对象内部还指向其他 Go 对象，而 C 会访问这些对象，就要分别固定。字符串、切片、map、channel 等值不能作为一个整体长期交给 C。

type PinnedBuffer struct {
    data   []byte
    pinner runtime.Pinner
}

func (b *PinnedBuffer) Pin(data []byte) unsafe.Pointer {
    if len(data) == 0 {
        return nil
    }
    b.data = data
    // 固定 backing array 的首元素，C 只接收地址和长度
    b.pinner.Pin(unsafe.SliceData(b.data))
    return unsafe.Pointer(unsafe.SliceData(b.data))
}

func (b *PinnedBuffer) Unpin() {
    // 先让 C 停止使用地址，再解除固定并释放 Go 引用
    b.pinner.Unpin()
    b.data = nil
}

用 cgocheck2 把隐藏路径拉出来

默认的 GODEBUG=cgocheck=1 会执行成本较低的动态检查，但检查不是完整证明。需要排查复杂桥接层时，可以在测试构建中启用 GOEXPERIMENT=cgocheck2，它在构建时启用更完整的指针处理检查，并带来额外运行开销。

# 使用默认动态检查跑最小复现，保留真实 panic 栈
GODEBUG=cgocheck=1 go test ./bridge -run TestCallback -count=1

# 在测试构建中启用更完整的 cgo 指针检查
GOEXPERIMENT=cgocheck2 go test ./bridge -run TestCallback -count=1

# 若还混有 unsafe 指针运算，再单独启用 checkptr 辅助定位
go test -gcflags=all=-d=checkptr=2 ./bridge -run TestCallback -count=1

不要把 GODEBUG=cgocheck=0 当成修复。关闭检查只会让违规路径更晚以数据损坏、悬空地址或不可预测崩溃出现。定位时应把调用缩小到一个 C 函数、一个传入地址和一个释放点，再判断是哪条生命周期越界。

完整修复检查表

• 看内存归属：地址来自 Go 堆还是 C 堆，不能靠 unsafe.Pointer 的类型推断。
• 看可达内容：传入区域是否含 slice、map、string、interface、函数或其他 Go 指针。
• 看保留时间：C 是否在调用返回后保存地址，是否转交线程、队列或回调注册表。
• 看释放责任：Handle.Delete、C.free、Pinner.Unpin 必须与 C 的最后一次使用对齐。
• 看空值边界：空切片不能直接取第一个元素地址，应传 nil/0 或直接返回。
• 看检查方式：保留默认 cgocheck，测试中再用 cgocheck2 收紧，而不是禁用检查。

常见问题

runtime.KeepAlive 能代替 Pinner 吗？

不能。KeepAlive 只延长 Go 值的可达时间，不保证 C 在调用返回后可以合法保存其地址；跨调用保留必须使用满足规则的 Pinner，或改用句柄、C 内存。

把 Go 指针转成 uintptr 存在 C 里可以吗？

不可以把它当成通用绕过方式。整数转换不会让 Go 内存脱离垃圾回收器管理，重新转回指针时仍可能成为悬空地址。需要回调上下文时使用 cgo.Handle。

为什么传 &slice[0] 有时没问题？

当 backing array 的元素不含 Go 指针、C 只在本次调用内访问且范围正确时，这是允许的短暂借用。只要元素含指针，或 C 在返回后继续使用，条件就不再成立。

最终可以把所有 cgo 指针 panic 归结为一张小配方：同步借用无指针数据区就直接传地址和长度；回调状态用 cgo.Handle；长期原始数据复制到 C 内存；确需长期保留 Go 地址时再用 Pinner，并把所有可达对象和释放时机一起纳入管理。