Go cgo 传递指针触发检查怎么办

Go 代码把指针传给 C 后触发 cgo argument has Go pointer to unpinned Go pointer 一类检查，通常不是“指针类型写错”，而是 C 端看到了禁止保存的 Go 内存关系。先按两个问题定位：这块内存由 Go 还是 C 分配？C 只在函数调用期间使用，还是会在返回后继续保存？临时借用、复制到 C 堆、runtime/cgo.Handle 和 runtime.Pinner 是四条不同路线，不能只把 GODEBUG=cgocheck=0 当修复。

先分清 Go 指针、C 指针和检查触发点

cgo 文档中的“Go 指针”按内存分配来源定义，不是按变量声明里的 *T 判断。new、取局部变量地址或 Go 切片底层数组得到的地址，属于 Go 内存；C.malloc 得到的地址属于 C 内存。一个 unsafe.Pointer 也可能在运行时代表任一来源。

更容易漏掉的是“指针的指针”：一个看似普通的结构体或切片，只要内部包含字符串、切片、map、interface、channel、函数或其他 Go 指针，就不能把这段 Go 内存交给 C 长期保存。Go 传给 C 的指针在普通函数调用期间会被隐式固定，但 C 返回后不能继续保存，除非它指向的是仍被 runtime.Pinner 固定的内存。

临时调用传递数据时，优先做 C 内存复制

如果 C API 只需要一段字符串或字节数据，复制到 C 堆最容易说明所有权。C.CString 和 C.CBytes 返回的是 C 内存，使用后必须调用 C.free；它们不会让 C 持有 Go 切片的底层地址。

package main

/*
#include 
#include 

// 这里只在调用期间读取 C 缓冲区，不保存指针。
static size_t consume_bytes(const void *p, size_t n) {
    if (p == NULL) { return 0; }
    return n;
}
*/
import "C"

import (
    "fmt"
    "unsafe"
)

func main() {
    data := []byte("payload")
    // C.CBytes 把 Go 字节复制到 C 堆，返回值由调用方释放。
    cbuf := C.CBytes(data)
    defer C.free(cbuf)

    // 传入长度，避免 C 端猜测字符串结束位置。
    n := C.consume_bytes(cbuf, C.size_t(len(data)))
    fmt.Println("C buffer length:", n)
}

这里的安全点不是 unsafe.Pointer 本身，而是 cbuf 指向 C 分配的内存，并且 C 函数没有把它保存到更长生命周期的结构中。若 C 接口会保存缓冲区，调用方还要把释放时机改成“C 释放完成之后”，不能继续使用示例里的函数级 defer。

需要跨调用保存 Go 值时，用 cgo.Handle 传句柄

把包含 Go 指针的对象直接写进 C 结构体，是最常见的违规方式。runtime/cgo.Handle 将 Go 值登记在 Go 侧，再把一个整数句柄传过 C；C 保存的是句柄而不是 Go 指针。句柄不用后必须 Delete，否则 Go 值会一直被句柄保持。

package main

/*
#include 

// C 端只保存整数句柄，不把 Go 对象地址写进自己的结构体。
static uintptr_t saved_handle;
static void remember_handle(uintptr_t h) { saved_handle = h; }
static uintptr_t load_handle(void) { return saved_handle; }
*/
import "C"

import (
    "fmt"
    "runtime/cgo"
)

func main() {
    value := map[string]string{"mode": "safe"}
    // NewHandle 登记带 Go 指针的值，C 侧只接收整数表示。
    handle := cgo.NewHandle(value)
    defer handle.Delete()

    C.remember_handle(C.uintptr_t(handle))
    // 取回前先把整数还原为 cgo.Handle，再由 Go 侧读取原值。
    restored := cgo.Handle(C.load_handle()).Value().(map[string]string)
    fmt.Println(restored["mode"])
}

Handle 不是万能的 C 指针替身：C 端只能把它当作不透明整数保存和回传，不能把它转成对象地址解引用。生产代码还应定义句柄的归属、回调线程和删除时机，避免 C 端回传已经删除的句柄。

只有确需固定内存时才使用 runtime.Pinner

如果 C 库确实需要在调用返回后继续访问某段 Go 内存，runtime.Pinner 可以延长这段内存的固定时间，但它不会改变“内存内部不能藏着未固定 Go 指针”的规则。固定的是数据区域，不是任意 Go 对象；字符串、切片、map 和 interface 也不能因为外面套了指针就自动变成可长期保存的 C 数据。

// 仅示意固定一段不含 Go 指针的字节数组；C 端必须在 Unpin 前停止使用。
var p runtime.Pinner
buf := new([8]byte)
p.Pin(buf)
defer p.Unpin() // 确认 C 已不再保存地址后再解除固定

// C.keep_bytes(&buf[0], 8) 只能在固定期间保存并访问该地址。

多数业务接口更适合让 C 侧自己 malloc 一块缓冲区，Go 用长度拷贝进出。这样生命周期由 C API 明确管理，也不需要把 Go 垃圾回收器的固定状态带进异步回调。

用四项清单复查 cgo 指针问题

排查时不要先改环境变量，按下面顺序记录证据：

1. 归属：地址来自 Go 分配、C 分配，还是经过 C.CBytes 等复制函数。
2. 内容：被指向区域是否包含字符串、切片、interface、map、函数或其他 Go 指针。
3. 时长：C 是只在当前调用读取，还是保存到全局、异步任务、回调上下文。
4. 清理：C 内存是否由明确的一方释放，Handle 是否 Delete，Pinner 是否严格成对 Pin/Unpin。

GODEBUG=cgocheck=0 只能关闭动态检查，不能让违规代码变得可移植；完整检查可用构建期的 GOEXPERIMENT=cgocheck2 辅助发现问题。修复后应保留默认检查，让测试覆盖“调用返回后仍访问”的异步路径。

常见问题

为什么一个 int 指针通常比结构体指针容易传递？

关键是被指向内存的内容。纯数值数组通常不含 Go 指针，而结构体字段可能间接包含切片或字符串，必须按整体内存关系判断。

把 Go 指针转成 uintptr 能绕过规则吗？

不能。类型转换不会改变内存来源和生命周期，反而会让垃圾回收和指针检查更难理解；跨调用保存值优先用 cgo.Handle。

什么时候不用 Pinner？

只要 C 端不需要保存 Go 地址，或者可以复制到 C 内存，就不用 Pinner。复制方案的所有权更清楚，也更适合异步 C API。