Go simd 代码在 WebAssembly 上为什么需要不同构建路径

我在整理 Go 的 SIMD 跨目标代码时，最容易被误导的一点是：看到“WebAssembly 支持 SIMD”，就以为把本地的 amd64 实现换成 GOARCH=wasm 已经结束了。真正需要拆开的，是 API 层、目标架构和运行时入口。可移植的 simd 可以在没有硬件向量指令的目标上走仿真；simd/archsimd 则暴露目标相关的向量类型，WebAssembly、amd64 和 arm64 的构建文件并不是同一份。

官方资料：https://go.dev/doc/go1.27

如果代码只依赖可移植的 simd，通常可以保留一套算法源码；如果直接使用 simd/archsimd 或架构汇编，就要按目标架构拆文件。浏览器的 js/wasm 和 WASI 的 wasip1/wasm 还要额外区分运行时依赖。

先把两种 SIMD 路径分清楚

Go 1.27 的可移植 simd 包提供大小不固定的向量类型，目标有硬件支持时可以使用硬件指令，暂不支持时可以使用仿真实现。它适合把“对一组数据做相同运算”写成一份公共算法。

simd/archsimd 是另一层：它直接表达目标相关的向量形状和操作。Go 1.27 为 WebAssembly 增加了 128 位 SIMD，也保留了 amd64 和 arm64 的专用实现，但该 API 仍是实验性的，类型和操作不能当成跨架构公共接口。

因此，“不同构建路径”不是 WebAssembly 一定不能复用 Go 代码，而是下面两种选择的代价不同：

GOOS 和 GOARCH 决定的是两层边界

编译 WebAssembly 时，GOARCH=wasm 表示目标架构，但 GOOS 仍然描述运行环境。浏览器通常使用 GOOS=js，WASI 则使用 GOOS=wasip1。两者同为 wasm，却不是同一个系统调用和宿主入口。

# 浏览器路径：依赖 wasm_exec.js 与 syscall/js 的入口
GOEXPERIMENT=simd GOOS=js GOARCH=wasm go build -o web/app.wasm ./cmd/web

# WASI 路径：面向 WASI 运行时，不要把浏览器专用依赖带进来
GOEXPERIMENT=simd GOOS=wasip1 GOARCH=wasm go build -o wasi/app.wasm ./cmd/wasi

上面的两个命令都启用了实验性 SIMD，但它们的可用依赖不同。浏览器入口可能需要 syscall/js，WASI 入口则应依赖 WASI 能提供的能力。把浏览器代码和算法代码放在同一个文件里，往往会让 WASI 构建在导入阶段就失败。

Go 的文件名和 //go:build 都能参与选择。foo_wasm.go 会匹配 wasm 架构；如果只适用于浏览器，则要写成 //go:build js && wasm，不能把“所有 wasm”误当成“浏览器”。

公共接口不变，专用实现分到不同文件

我会把跨目标 SIMD 代码拆成“公共接口 + 目标实现 + 保底实现”三层。公共层只描述业务动作，例如把两个浮点切片相加；目标层决定是否调用 archsimd；保底层则在实验 API 不可用或目标没有对应指令时维持正确结果。

//go:build wasm

package kernel

import "simd/archsimd"

// add4 使用 wasm 的 128 位向量，一次处理 4 个 float32。
func add4(dst, a, b []float32) {
	// 调用方负责保证切片至少有 4 个元素，尾部交给公共循环处理。
	x := archsimd.LoadFloat32x4(a)
	y := archsimd.LoadFloat32x4(b)
	x.Add(y).Store(dst)
}

//go:build !wasm

package kernel

// add4 是没有 wasm 专用实现时的安全回退，保持同一公共接口。
func add4(dst, a, b []float32) {
	// 逐元素计算不依赖目标向量宽度，便于其它架构先通过构建。
	for i := 0; i 

示例只展示文件选择关系，公共循环还需要处理长度不足一个向量的尾部。若改用可移植 simd，则可以把向量运算放入公共文件，减少 _wasm.go 与 _amd64.go 的差异；若使用 archsimd，就应把向量类型留在目标文件内，不要把 Float32x4 这类类型暴露到跨架构公共 API。

构建时要同时检查实验开关和运行时入口

这类问题常见的误判有三个。第一，只设置 GOARCH=wasm，却忘记 GOEXPERIMENT=simd，于是实验包无法导入。第二，把 js/wasm 的入口当成所有 wasm 目标的入口，WASI 构建被迫携带 syscall/js。第三，只按文件名拆了 _wasm.go，却没有给公共回退留下可选实现。

# 浏览器目标的源码选择：wasm + js
GOEXPERIMENT=simd GOOS=js GOARCH=wasm go list -deps ./cmd/web

# WASI 目标的源码选择：wasm + wasip1
GOEXPERIMENT=simd GOOS=wasip1 GOARCH=wasm go test ./...

# 需要确认某个文件是否带有目标约束时，优先检查 go:build 与文件名
# 不要把下面的输出当成文章中的固定结果，实际依赖由项目决定。
go help buildconstraint

如果项目要同时支持浏览器和 WASI，建议把入口拆成 cmd/web 与 cmd/wasi，把向量算法放在不依赖宿主的内部包。然后分别为 js && wasm、wasip1 && wasm 和通用目标提供适配文件。这样即使 SIMD 实验 API 发生变化，改动也集中在实现层。

最后用一张清单决定走哪条路

• 只想让同一套算法跑在多个目标：优先使用可移植 simd，接受目标不支持时的仿真回退。
• 需要直接使用 WebAssembly 128 位向量：启用 GOEXPERIMENT=simd，把 simd/archsimd 留在 wasm 文件中。
• 需要浏览器 API：使用 js && wasm 的构建约束；需要 WASI：单独使用 wasip1 && wasm 入口。
• 需要维护多个架构：公共接口只暴露业务动作，专用向量类型和尾部处理留在目标实现里。
• 实验 API 不是稳定兼容承诺：把 Go 版本和 GOEXPERIMENT 写进构建说明，并为回退实现保留测试路径。

相关问题

WebAssembly 目标一定要使用 simd/archsimd 吗？

不一定。若算法可以接受仿真或由可移植 simd 表达，公共实现更容易维护；只有需要明确使用 WebAssembly 128 位操作时，才进入 simd/archsimd。

为什么同样是 wasm 还要区分 js 和 wasip1？

因为它们对应不同宿主运行时。GOARCH=wasm 只说明指令目标，GOOS 决定能否使用浏览器绑定、WASI 能力和对应的入口文件。

能不能只保留一个 _wasm.go？

只有在浏览器和 WASI 依赖完全相同且不导入宿主专属包时才适合。实际项目通常应再用 js && wasm 或 wasip1 && wasm 收窄入口。