项目全称与地址：
github.com/ebitengine/purego（简称 PureGo 或 purego）
- 当前最新版本：v0.10.0（2026 年 2 月发布）
- 最新提交：2026 年 3 月 15 日
- Stars：约 3.5k
- 许可证：Apache-2.0（核心）+ BSD-3-Clause（复制的 runtime/cgo 代码）
- 起源：Ebitengine（著名纯 Go 游戏引擎）团队，为实现“真正纯 Go 跨平台编译”而生。
1. 设计思想（Design Philosophy）
PureGo 的核心理念是 “纯 Go 优先 + 最大可移植性”，具体体现为：- 消除 CGO 依赖：传统 CGO 需要 C 工具链（gcc/clang），导致跨编译困难（尤其是 Windows/macOS 到 Linux）、构建缓存失效、二进制变大。PureGo 彻底绕过，让
CGO_ENABLED=0 go build就能跑。 - 动态链接 + 运行时加载：不静态链接，而是
dlopen/LoadLibrary在运行时加载 .so/.dll/.dylib，支持插件系统、热更新、调用其他语言编译的共享库。 - 重用 Go 运行时：不重复造轮子，大量代码直接复制/适配 Go 源码中的
runtime/cgo（ABI 定义、栈切换、callback 机制），保证 ABI 准确性，同时通过internal/fakecgo在无 CGO 环境下模拟 cgo 行为。 - 渐进式 + 容错：支持 CGO 共存（
CGO_ENABLED=1时自动回退），Tier 1/2 分级支持（关键架构严苛测试，边缘架构尽力而为）。 - 性能与简单性权衡：调用开销接近 CGO（非零成本），但换来极致的跨平台性和构建速度。目标用户是游戏、多媒体、AI 绑定、嵌入式、WASM 外场景。
extern "C" 一样简单，却保留 Go 的纯净与可移植性”。2. 架构设计（Architecture）
采用分层 + 平台/架构特化设计，高度模块化，便于维护多平台：- 高层 API 层（用户直接使用）：
Dlopen/Dlsym/Dlclose（动态加载）RegisterLibFunc/RegisterFunc（C → Go 调用）NewCallback（Go → C 回调）SyscallN（低级 syscall）- 平台抽象层：
dlfcn_*.go/dlfcn_nocgo_*.go（Linux/Darwin/FreeBSD/NetBSD/Android/Windows 不同实现）syscall_*.go+syscall_unix.go等- 架构特化层（核心性能与 ABI 正确性）：
- 每个 GOARCH 独立文件：
struct_*.go（结构体布局）、abi_*.h（调用约定定义，从 runtime/cgo 复制） - 汇编文件（.s）：
sys_*.s（系统调用存根）、zcallback_*.s（回调 trampoline）、dlfcn_stubs.s - 内部核心模块（internal）：
internal/fakecgo：完整模拟 cgo runtime（栈切换、callback 注册、环境变量等），让无 CGO 也能跑。objc/：macOS Objective-C 专属支持（协议、运行时创建）。
这种架构确保 “一次实现、多架构复用” ，维护成本集中在少数 .s 和 struct_*.go 文件。
3. 实现细节（Implementation）
PureGo 的实现极其精巧，混合 Go + 少量汇编 + 反射 + unsafe：- 库加载（Dlopen）：
- POSIX：通过纯 syscall 调用 libc 的
dlopen/dlsym（使用dlfcn_stubs.s自举）。 - Windows：
LoadLibrary+GetProcAddress。 - 支持
RTLD_NOW|RTLD_GLOBAL等 flag。 - C 函数调用（RegisterFunc / RegisterLibFunc）：
var puts func(string)
purego.RegisterLibFunc(&puts, libc, "puts") // 关键一行！
reflect.MakeFunc动态创建 wrapper 函数。- 根据
abi_*.h计算参数布局（整数寄存器、浮点寄存器、栈槽、hidden return pointer）。 - 参数转换：string → C 字符串（自动 null-terminated + 临时 buffer + KeepAlive）、struct 按内存布局拷贝、func → NewCallback。
- 使用 pooled
syscall15Args结构体打包后，通过runtime.cgocall（fakecgo 版）或直接 assembly 调用 C 函数指针。 - 支持返回值提取（包括 struct、float）。
- Go 函数被 C 调用（NewCallback）：
cb := purego.NewCallback(myGoFunc) // 返回 uintptr，可传给 C
- 返回一个 assembly trampoline（
zcallback_*.s）。 - trampoline 负责栈切换 + calling convention 转换 → 跳转到公共 handler
callbackasm1→ 调用真实 Go 函数。 - 支持 struct 参数/返回值（近期大更新）。
- 特殊技巧：
internal/fakecgo：完整复制 Go runtime/cgo 的callbacks.go、setenv.go等，实现无 CGO 时的runtime.setg栈管理。- Darwin ARM64 特殊处理：字节级栈打包。
- Variadic 函数：通过
[]any模拟。 - Windows 386/arm：部分依赖 CGO（受限功能）。
4. 使用示例（直接可跑）
package main
import (
"fmt"
"runtime"
"github.com/ebitengine/purego"
)
func getSystemLibrary() string {
switch runtime.GOOS {
case "darwin": return "/usr/lib/libSystem.B.dylib"
case "linux": return "libc.so.6"
default: panic("unsupported")
}
}
func main() {
lib, err := purego.Dlopen(getSystemLibrary(), purego.RTLD_NOW|purego.RTLD_GLOBAL)
if err != nil { panic(err) }
var puts func(string)
purego.RegisterLibFunc(&puts, lib, "puts")
puts("PureGo：无需 CGO 也能调用 C！")
}
CGO_ENABLED=0 go run .更多示例见 repo 的 examples/ 目录（libc、GTK、libvips 等真实绑定）。
5. 优缺点与对比
vs CGO ：- 优点：跨编译简单、构建快、二进制小、动态加载、插件友好。
- 缺点：复杂结构体/复杂回调支持稍弱（仍在迭代）、调用开销接近但非更优、beta 阶段需关注 issue。
- PureGo 是 纯 Go 原生，无需额外 C 依赖；libffi 需要链接 C 库，跨平台更麻烦。
- PureGo 在 Go 生态内更自然（反射 + runtime 集成）。
//go:build purego表示“禁用汇编，使用纯 Go 后备实现”。- PureGo 库本身可与此 tag 结合使用（很多高性能库如 chdb、easytier 都已采用）。
6. 适用场景与未来展望
- 已广泛用于：Ebitengine、chdb Go SDK、libvips 绑定、GTK/Adwaita、物理引擎、向量搜索（llama.cpp）、插件系统。
- 特别适合：游戏、多媒体、AI 推理绑定、嵌入式、WASM 外环境、需要跨平台静态二进制的项目。
- 未来：继续完善 Tier 2 架构（riscv64、loong64 等）、增强 struct 支持、性能优化（更多 SIMD 友好绑定）、可能被 Go 标准库参考。
官方 Repo：https://github.com/ebitengine/purego （文档、Discord 讨论都很活跃）。