Go 1.24 go:wasmexport 如何导出宿主可调用函数：参数边界与宿主调用实验

把 Go 代码嵌进宿主程序时，过去常见的做法是把逻辑包成命令模块，再通过启动参数或 JavaScript 胶水层沟通。Go 1.24 多了一条更直接的路：用 go:wasmexport 把指定函数导出给 WebAssembly 宿主，再用 WASI reactor 让同一个实例持续接受调用。本文把这条路径放进一个宿主调用实验里，重点核对函数何时可调用、参数怎样映射，以及哪些写法会在编译阶段被挡住。

最小可行组合是：Go 1.24 的 go:wasmexport + GOOS=wasip1 GOARCH=wasm + -buildmode=c-shared；宿主先调用 _initialize，再按导出名调用 add。

Go 1.24 的导出能力解决了哪一段连接问题

官方博客给出的核心变化有两个：go:wasmexport 让编译器把函数登记为 Wasm export，GOOS=wasip1 GOARCH=wasm 配合 -buildmode=c-shared 可以构建持续存活的 WASI reactor。这样，宿主不必每次请求都重新启动一个命令模块，而是初始化一次后重复调用导出函数。

这个区别对插件尤其有用。宿主只需要约定函数名和参数类型，Go 模块内部仍可以保留自己的包结构。本文的宿主调用实验只做一件事：把两个 int32 相加，并由宿主连续调用两次，观察实例是否还活着。

先写一个能被宿主找到的 add

建立实验目录后，导出指令必须紧挨着函数定义。指令中的 add 是宿主看到的导出名，下面的 Go 函数名也可以不同；为了让实验便于对照，两个名字保持一致。

package main

//go:wasmexport add
func add(a, b int32) int32 {
    return a + b
}

func main() {}

编译命令也有两个容易漏掉的条件：

GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -o reactor.wasm

这里的 main 只是让程序具备可构建的入口，并不是 reactor 的业务启动点。Go 1.24 的链接器会生成 _initialize，宿主必须先调用它完成运行时和包初始化，再查找 add。

宿主调用实验：_initialize 之后再调用 ExportedFunction

用 Wazero 作为宿主时，调用顺序可以压缩成下面几步。WithStartFunctions("_initialize") 会让实例化阶段运行初始化函数，随后通过 ExportedFunction("add") 得到导出函数。

r := wazero.NewRuntime(ctx)
defer r.Close(ctx)
wasi_snapshot_preview1.MustInstantiate(ctx, r)

config := wazero.NewModuleConfig().WithStartFunctions("_initialize")
wasmModule, err := r.InstantiateWithConfig(ctx, wasmFile, config)
if err != nil {
    return err
}

fn := wasmModule.ExportedFunction("add")
res, err := fn.Call(ctx, api.EncodeI32(1), api.EncodeI32(2))
if err != nil {
    return err
}
fmt.Println(api.DecodeI32(res[0]))

第一次调用得到 3 后，可以继续用同一个 fn 调用 add(2, 3)，结果应为 5。这验证的是 reactor 实例仍然存在，不是 Go 的 main 被重复运行。若跳过初始化，或者把导出名写成不存在的字符串，问题会出现在宿主装载或函数查找阶段，而不是加法逻辑本身。

参数边界：Go 类型不是随意映射到 Wasm

编译器文档给出了明确映射。int32 和 uint32 变成 i32，int64 和 uint64 变成 i64；float32、float64 分别变成 f32、f64。布尔值在 Wasm 层也是 i32。

字符串并不是一个 Wasm 原生字符串值，而是指针和长度的组合；指针也不是“把 Go 堆对象地址交给 64 位宿主”。指令文档特别限制了指针元素类型，包含指针字段的普通结构体不能直接跨这个边界。把导出函数设计成少量整数、浮点数或明确的字符串参数，通常比试图传递复杂对象更稳。

和 js/wasm 胶水层相比，什么时候值得换成 reactor

js/wasm 仍适合浏览器页面直接调用 JavaScript 环境；WASI reactor 面向的是能够加载 Wasm 模块的宿主程序。两者都能运行 Go 编译出的 Wasm，但入口模型不同：前者通常依赖 wasm_exec.js 和 JavaScript 全局对象，后者围绕 _initialize 与明确的 Wasm export 组织调用。

如果插件只需要被宿主按函数协议调用，reactor 的边界更清楚；如果逻辑高度依赖 DOM、定时器或浏览器对象，迁移到 WASI 并不会自动带来这些能力。别先看“能不能编译”，先画清宿主提供的导入、模块导出的函数和状态生命周期。

常见问题：导出函数接入时最容易踩的坑

为什么导出了 add，宿主却找不到它？

先确认编译器是 Go 1.24 或更新版本，再核对 //go:wasmexport add 是否紧挨函数定义。宿主查找时必须使用导出名 add，不能凭习惯改成 Go 包路径。

必须手动调用 _initialize 吗？

需要完成一次初始化。使用 Wazero 时，可以通过 WithStartFunctions("_initialize") 让实例化流程调用它；无论采用哪种宿主，原则都是先初始化，再调用其他导出函数。

导出函数能返回 string 吗？

不能按普通 Go 返回值处理。编译器文档允许字符串作为参数，并映射成指针与长度，但字符串不允许作为结果；需要返回文本时，应设计宿主可理解的内存协议或返回整数状态。

把 wasm.Exec 实验收敛成插件协议

这个实验的价值不在于把 add 做复杂，而在于固定一条可验收的调用链：构建出 reactor，初始化 _initialize，按名称拿到 ExportedFunction，用可映射的参数调用，再检查结果。真正接入业务时，把函数名、参数顺序、错误码和内存所有权写成宿主与插件共同遵守的协议，先用两个连续调用验证实例生命周期，再逐步增加功能。