Go 指针为什么不能随意交给 C 长期保存，规则保护了什么

Go 指针不能随意交给 C 长期保存，根本原因不是“C 不认识 Go 的地址”，而是C 位于 Go 垃圾回收器的对象图之外。如果 C 在 cgo 调用返回后仍持有普通 Go 指针，运行时就难以确认谁还引用该对象、对象是否必须固定，以及对象内部是否藏着其他未固定的 Go 指针。

cgo 的限制保护三个不变量：GC 能找到所有指向 Go 内存的引用；外部仍在访问的 Go 内存必须保持固定；交给 C 的内存不能隐藏未固定的嵌套 Go 指针。长期保存数据时，优先复制到 C 堆；确实要保留特定 Go 内存时才使用 runtime.Pinner；保存回调上下文时使用整数形式的 runtime/cgo.Handle。

cgo 指针规则：https://pkg.go.dev/cmd/cgo

Pinner 文档：https://pkg.go.dev/runtime#Pinner

Handle 文档：https://pkg.go.dev/runtime/cgo#Handle

保护的不是地址值，而是可追踪对象图

cgo 文档对 Go 指针和 C 指针的定义是动态的：内存由 Go 分配，就是 Go 指针；内存由 C.malloc 等 C 分配器分配，就是 C 指针。判断依据与 Go 变量写成 *C.char、unsafe.Pointer 还是 uintptr 无关。改变类型不会改变内存的真正所有者。

垃圾回收器必须知道每个 Go 指针的位置，才能判断对象是否仍然可达。C 内存不由 Go GC 扫描，因此把一个指向 Go 对象的地址写入 C 全局变量、C 结构体或异步任务后，不能假设 GC 会自动把这条引用纳入对象图。

Go 指针规则也不只约束显式指针。interface、map、channel、函数等非零值必然含有 Go 指针；slice 和 string 含有数据引用；数组与结构体是否含指针则取决于字段。把这些值的地址交给 C，不等于只交出一段无指针字节。

四条高风险路径分别破坏什么

官方规则允许 C 保存 Go 指针的前提，是其指向的内存在整个保存期间都处于 pinned 状态。函数参数指向的 Go 内存在 cgo 调用期间会被隐式固定，但这种固定通常在函数返回时结束，所以“这次调用没崩”不能证明异步回调或后台线程继续访问是安全的。

同步调用只借用 Go 缓冲区

如果 C 函数在返回前完成读取，不缓存指针，也不启动异步任务，那么可以把无 Go 指针的字节后备数组借给 C。指向 slice 元素时，规则考察的是整个后备数组；因此后备数组必须满足没有未固定 Go 指针的条件。[]byte 是常见且合适的边界类型。

func checksum(data []byte) (uint32, error) {
    if len(data) == 0 {
        return 0, errors.New("输入不能为空")
    }

    // 只在本次同步调用期间借用 Go 的字节后备数组。
    // C.checksum 返回后不得缓存、排队或再次访问这个地址。
    value := C.checksum(
        (*C.uchar)(unsafe.Pointer(&data[0])),
        C.size_t(len(data)),
    )
    // KeepAlive 只保证 data 在这一位置之前存活，不会延长固定期。
    runtime.KeepAlive(data)
    return uint32(value), nil
}

runtime.KeepAlive 解决的是编译器和 GC 观察到的存活终点，不是地址固定协议。它不能让 C 在函数返回后继续保存地址，也不能把含 Go 指针的对象变成可长期交给 C 的对象。

长期保存数据时优先复制到 C 堆

当 C 库需要缓存配置、密钥材料、音频块或异步任务输入时，最容易审计的做法是复制。C.CBytes 在 C 堆创建副本，C 可以按自己的生命周期保存它；代价是必须明确由谁、何时调用 C.free。这把问题从“跨 GC 边界持有 Go 指针”转换为普通的 C 资源所有权。

func retainCopy(data []byte) (unsafe.Pointer, C.size_t, error) {
    if len(data) == 0 {
        return nil, 0, errors.New("数据不能为空")
    }

    // C.CBytes 会复制内容到 C 堆，返回值不再是 Go 指针。
    ptr := C.CBytes(data)
    if ptr == nil {
        return nil, 0, errors.New("分配 C 堆副本失败")
    }
    return ptr, C.size_t(len(data)), nil
}

func releaseCopy(ptr unsafe.Pointer) {
    if ptr == nil {
        return
    }
    // 只有确认 C 已停止访问后才能释放，且必须只释放一次。
    C.free(ptr)
}

复制方案尤其适合 string、slice 或复杂 Go 对象，因为这些值本身包含 Go 指针，不能简单地把值头部固定后交给 C 长期保存。跨边界格式最好保持为长度明确的字节、整数、浮点数或纯 C 结构。

runtime.Pinner 只用于可证明的固定场景

runtime.Pinner 可以让符合条件的 Go 对象在一次 cgo 调用结束后仍保持固定。它适合 C API 明确要求保留一块 Go 分配的无指针缓冲区，而复制成本又确实不可接受的场景。Pinner 自身也必须在 C 保存引用期间保持可达；调用 Unpin 前，必须先让 C 停止使用地址。

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

func NewPinnedBuffer(size int) (*PinnedBuffer, error) {
    if size 

一个 Pinner 可以固定多个对象，Unpin 会解除它管理的所有固定对象。若被固定对象内部还包含指向其他 Go 对象的指针，而 C 会沿这些指针访问，则相关对象也必须分别固定。字符串、slice、channel 等值不能因为持有 Pinner 就整体变成可供 C 长期保存的值。

回调上下文用 runtime/cgo.Handle

很多 C API 需要一个 user_data 或 context，注册时保存，回调时原样传回。此时 C 通常不需要解引用 Go 对象，只需要稳定标识。runtime/cgo.Handle 用一个足够大的整数代表任意 Go 值，C 保存的是整数，回到 Go 后再恢复值。

func registerCallbackContext(v any) C.uintptr_t {
    // Handle 是整数标识，C 可以保存并在回调时原样传回。
    return C.uintptr_t(cgo.NewHandle(v))
}

func loadCallbackContext(raw C.uintptr_t) any {
    // 只在 Go 回调中把有效整数句柄还原为原始 Go 值。
    return cgo.Handle(raw).Value()
}

func unregisterCallbackContext(raw C.uintptr_t) {
    // 确认 C 不再持有该值后删除；重复删除或读取无效句柄会 panic。
    cgo.Handle(raw).Delete()
}

Handle 的零值无效，适合用作 C API 的哨兵。它会占用运行时资源，必须在最后一次回调完成且 C 不再保留该整数后调用 Delete。不要把 Handle 整数强制转换为假 Go 指针；正确做法是让 C 把整数原样传回。

检查、审计与风险分级

cgo 会在运行时检查一部分指针传递规则。默认的 GODEBUG=cgocheck=1 提供成本较低的动态检查；更完整的检查需要在构建时启用 GOEXPERIMENT=cgocheck2。不要把关闭检查当成修复方式。unsafe 可以让部分错误躲过检查，但违反规则的程序可能以不可预测的方式崩溃或损坏数据。

发布前至少确认：

1. 每个传给 C 的地址都能说明由 Go 还是 C 分配。
2. 同步借用的 C 函数不会缓存地址、排队或启动异步任务。
3. C 长期保存的数据拥有明确的释放 API 和唯一所有者。
4. 使用 Pinner 时，C 先停止访问，Go 后 Unpin，相关嵌套对象均满足规则。
5. 回调上下文使用 Handle，并在 C 不再持有后 Delete。
6. 没有用 KeepAlive、uintptr 或 unsafe 冒充固定与所有权协议。
7. 测试环境保留默认 cgocheck，并在关键构建中评估 cgocheck2。

常见问题

把 Go 指针转换成 uintptr，C 就能长期保存吗？

不能。转换只改变位模式的表达方式，不会让 GC 追踪 C 内存，也不会固定对象或延长其存活期。C 需要回传上下文时使用 runtime/cgo.Handle；要访问实际内存时选择 C 堆复制或受控的 Pinner。

runtime.KeepAlive 能代替 Pin 吗？

不能。KeepAlive 防止对象在指定代码位置之前被判定为不可达；Pin 则防止对象在约定期间被移动或释放，并允许 C 在规则范围内保存地址。两者解决的是不同问题。

C.malloc 返回的指针可以由 Go 长期保存吗？

可以，只要遵守对应 C API 的所有权和释放要求。它指向 C 分配的内存，不是 Go 指针，Go GC 不会自动释放它，因此必须明确调用 C.free 或库提供的销毁函数。

能不能直接 Pin 一个 slice 或 string？

不能把 slice 头或 string 值当成可供 C 长期保存的普通对象。对于无指针的字节数据，可以固定其后备数组中的对象并只交出数据地址；字符串等场景通常更适合复制到 C 堆。

cgo 指针规则不是为了阻止 Go 与 C 共享数据，而是要求共享必须有可证明的存活期、固定期和所有权。同步读取就短期借用，长期数据就复制，特殊的固定内存用 Pinner，回调上下文用 Handle。把这四种场景分开，跨语言边界才能既可运行，也可审计。