goffi与purego冲突

Go FFI 库 purego 与 goffi 的共存冲突问题记录

背景与环境

在开发一个依赖 gogpu/wgpu（GPU 计算）和 turso.tech/database/tursogo（本地嵌入式数据库）的项目时，我遇到了一个令人困惑的构建问题。项目同时引入了两个 Go FFI (Foreign Function Interface) 库：

  • github.com/ebitengine/purego (v0.10.1) —— 由 tursogo 间接引入
  • github.com/go-webgpu/goffi (v0.5.5) —— 由 gogpu/wgpu 间接引入

构建环境：GOOS=linux, GOARCH=amd64。

问题现象

阶段一：CGO 启用时的错误

在默认构建（CGO_ENABLED=1）时，出现如下链接错误：

1
2
3
dlopen_stub: unhandled relocation for goffi_dlopen (type 65 (SDYNIMPORT) rtype 7 (R_CALL))
dlsym_stub: unhandled relocation for goffi_dlsym (type 65 (SDYNIMPORT) rtype 7 (R_CALL))
dlerror_stub: unhandled relocation for goffi_dlerror (type 65 (SDYNIMPORT) rtype 7 (R_CALL))

阶段二：尝试关闭 CGO 后的新冲突

根据 goffi 的文档建议，尝试使用 CGO_ENABLED=0 构建，以绕过 CGO 依赖。但此时出现了新的、更根本的链接冲突：

1
link: duplicated definition of symbol _cgo_init, from github.com/go-webgpu/goffi/internal/fakecgo (type SDATA size 8) and github.com/ebitengine/purego/internal/fakecgo (type SDATA size 8)

依赖链追溯

通过 go mod why 命令，明确了冲突依赖的来源：

  • purego 是 turso.tech/database/tursogo 的依赖，用于实现无 CGO 的本地数据库操作（libSQL/SQLite）。
  • goffi 是 github.com/gogpu/wgpu 的依赖，用于实现无 CGO 的 GPU（WebGPU）计算调用。

根本原因分析

这个问题的根源在于 purego 和 goffi 在”无 CGO”模式下的实现机制发生了冲突。

1. fakecgo 的”模拟器”角色

当 CGO_ENABLED=0 时，Go 程序无法使用真实的 CGO 运行时来调用 C 代码。为了能执行 dlopen、dlsym 等动态链接操作，purego 和 goffi 都会在内部提供一个名为 internal/fakecgo 的包。这个包的作用是模拟一个最小化的 CGO 环境，以”欺骗”Go 运行时和链接器，让它相信存在一个 CGO 环境。

2. 符号 _cgo_init 的独占性

模拟 CGO 环境的关键一步，就是向 Go 链接器提供一个名为 _cgo_init 的全局符号。这个符号是模拟环境的”入口”或”开关”，在最终的二进制文件中必须全局唯一。

3. 根本冲突

purego 和 goffi 各自实现并提供了自己的 _cgo_init 符号。当它们被同时链接到同一个程序中时，链接器发现了两个同名的全局符号定义，无法决定使用哪一个，于是报告”重复定义”错误。

结论： 这两个库在 CGO_ENABLED=0 模式下，并非”不使用 CGO”，而是”各自实现了互不兼容的 CGO 模拟器”。因此，它们无法在同一个 Go 程序中共存。这是一个架构设计上的根本性冲突。

解决方案

解决问题的唯一方法是在 goffi 和 purego 之间做出选择，统一底层 FFI 技术栈。

方案一：统一使用 goffi（保留 GPU 功能）

此方案意味着需要移除或替换引入 purego 的 tursogo 库。

  1. 寻找 tursogo 的替代品：
    • 评估纯 Go 的 libSQL/SQLite 驱动，如 github.com/tursodatabase/go-libsql 或其他 SQLite 驱动。
    • 如果必须使用 Turso 服务，考虑使用其 HTTP API 接口，而非本地嵌入式副本。
  2. 验证兼容性：确保替代方案不引入 purego 或任何其他 FFI 模拟库。

方案二：统一使用 purego（保留数据库功能）

此方案意味着需要移除或替换引入 goffi 的 GPU 库。

  1. 评估 GPU 功能的必要性：确认项目是否真的需要本地 GPU 计算，或者能否通过其他方式（如 CPU 计算、远程 GPU 服务）替代。
  2. 寻找 goffi 的替代品：如果必须保留 GPU 功能，研究 gogpu/wgpu 是否提供了基于 purego 的后端（可能性较低），或者寻找其他不依赖 goffi 的 WebGPU Go 绑定。

方案三：架构隔离（终极方案）

如果两个功能都必须保留且无法替换，只能进行架构层面的拆分：

  1. 拆分为两个独立服务：
    • 服务 A：包含 GPU 计算功能，使用 goffi 技术栈。
    • 服务 B：包含数据库操作功能，使用 purego 技术栈。
  2. 进程间通信：两个服务通过 RPC（如 gRPC）、HTTP API 或消息队列进行通信。
  3. 独立构建与部署：每个服务独立构建、测试和部署，彻底隔离构建环境。

诊断命令汇总

以下是排查过程中用到的有用命令：

1
2
3
4
5
6
7
8
9
10
11
# 查看完整构建日志
go build -work -x 2>&1 | grep -E "dlopen_stub|dlsym_stub|dlerror_stub|goffi"

# 确认 CGO_ENABLED 状态
go build -work -x 2>&1 | grep "CGO_ENABLED"

# 定位 purego 依赖来源
go mod why github.com/ebitengine/purego

# 查看所有依赖
go mod graph | grep -E "purego|goffi"

结论与教训

  1. purego 和 goffi 在 CGO_ENABLED=0 下无法共存，这是一个设计上的硬冲突，不是简单的 Bug。
  2. 在引入底层 FFI 库时，必须注意技术栈的统一。同时使用多个模拟 CGO 的库会直接导致链接器符号冲突。
  3. 排查此类问题时，go mod why 和构建详细日志（go build -x）是定位依赖来源的有力工具。
  4. 当间接依赖发生冲突时，架构拆分往往是最后但最彻底的解决方案。

记录时间： 2026-07-03
相关环境： Go 1.21+, linux/amd64
涉及依赖： turso.tech/database/tursogo (引入 purego), github.com/gogpu/wgpu (引入 goffi)