Compilación con GOOS=wasip1 GOARCH=wasm

El destino WASI de Go convierte paquetes ordinarios en módulos .wasm portátiles.

El comando de compilación es similar a la compilación cruzada a Linux o Windows: configura GOOS y GOARCH, y luego go build.

Comprender qué flags son importantes y qué archivos (wasm_exec.js) pertenecen a un destino diferente mantiene correctos tus scripts de compilación y matrices de CI.

Resumen

GOOS=wasip1 con GOARCH=wasm selecciona la superficie de llamadas al sistema WASI Preview 1.

El enlazador de Go emite un módulo que importa funciones de wasi_snapshot_preview1 en lugar de llamadas al sistema específicas de la plataforma.

Ejecutas el artefacto con un host WASM externo (wasmtime, wazero, Spin) en lugar del comando go.

Las compilaciones de lanzamiento comúnmente pasan -ldflags="-s -w" para eliminar metadatos de depuración.

Las notas sobre wasm_exec.js para destinos de navegador no se aplican a la salida wasip1.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

GOOS=wasip1 GOARCH=wasm go build -ldflags="-s -w" -o app.wasm .
wasmtime run app.wasm

Cuándo usar esto:

• Herramientas CLI portátiles distribuidas como un único artefacto .wasm
• Plugins en sandbox ejecutados dentro de un servicio Go a través de wazero
• Funciones de borde en Spin/Fermyon o hosts WASM compatibles
• Compilaciones verificadas por CI que no deben depender de binarios nativos del SO
• Lógica de negocio compartida compilada una vez e incrustada en múltiples aplicaciones host

Ejemplo de Trabajo

package main
 
import (
    "encoding/json"
    "fmt"
    "os"
)
 
type config struct {
    Name string `json:"name"`
}
 
func main() {
    raw := os.Getenv("CONFIG_JSON")
    if raw == "" {
        fmt.Fprintln(os.Stderr, "CONFIG_JSON required")
        os.Exit(1)
    }
    var cfg config
    if err := json.Unmarshal([]byte(raw), &cfg); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
    fmt.Printf("hello, %s\n", cfg.Name)
}

go mod init example.com/wasigreet
# guarda main.go, luego:
GOOS=wasip1 GOARCH=wasm go build -ldflags="-s -w" -o greet.wasm .
wasmtime run --env CONFIG_JSON='{"name":"Ada"}' greet.wasm

Lo que esto demuestra:

• Paquetes de la biblioteca estándar (encoding/json, os) se compilan para WASI sin tags.
• Las variables de entorno son capacidades proporcionadas por el host (--env en wasmtime).
• Los códigos de salida se propagan al proceso host como una CLI nativa.
• La salida de error en os.Stderr se mapea a los streams stderr del host.

Inmersión Profunda

Cómo Funciona

• El compilador de Go reduce las goroutines y el GC a instrucciones WASM más importaciones de tiempo de ejecución.
• wasip1 mapea las operaciones de archivo de os a las APIs de fd de WASI que el host debe implementar.
• La exportación _start es el punto de entrada que el host llama después de instanciar la memoria lineal.
• go mod y el vendoring funcionan igual que las compilaciones nativas; cgo no está disponible en este destino.

Referencia del Entorno de Compilación

wasm_exec.js vs WASI

No copies GOROOT/misc/wasm/wasm_exec.js en los paquetes de despliegue WASI.

Notas de Go

// Archivos de entrada de navegador separados - nunca compiles estos en compilaciones wasip1.
//go:build js && wasm
 
package browseronly

# Patrón de Makefile
build-wasi:
	GOOS=wasip1 GOARCH=wasm go build -ldflags="-s -w" -o bin/app.wasm ./cmd/app

Errores Comunes

• Asumir que go run funciona - No hay un emulador WASI dentro de go run; debes ejecutar con un host WASM. Solución: envuelve wasmtime run o wazero en objetivos go:generate/Makefile.

• Escrituras en el sistema de archivos sin pre-apertura - os.Create("/tmp/x") falla si el host no mapeó /tmp. Solución: pasa wasmtime run --dir /host/tmp::/tmp o configura wazero FSConfig.

• Mezclar archivos js/wasm en paquetes WASI - Las importaciones accidentales de syscall/js rompen la compilación wasip1. Solución: aisla el código del navegador detrás de los tags de compilación js && wasm.

• Esperar red completa - WASI preview 1 no garantiza APIs de TCP en todos los tiempos de ejecución. Solución: confirma el soporte de sockets o usa triggers HTTP de Spin.

• Binarios enormes por sorpresa - El tiempo de ejecución completo de Go añade megabytes incluso para fmt.Println. Solución: mide el tamaño pronto; considera TinyGo o divide las rutas "calientes".

• GOOS=wasi obsoleto - Documentación más antigua hace referencia a wasi; las herramientas modernas usan wasip1. Solución: actualiza los scripts a wasip1 para Go 1.21+.

Alternativas

Preguntas Frecuentes

Relacionado

• Go en WebAssembly: Rutas de Navegador, WASI y Embebidas - visión general de tres rutas
• Runtimes Host WASI: wasmtime, wazero y Spin - ejecuta e incrusta módulos
• syscall/js: Go en el Navegador - cuando necesitas js/wasm en su lugar
• Optimización de Tamaño de WASM: TinyGo vs gc WASM - tácticas de enlazador e importación
• Mejoras en el Tiempo de Ejecución y Memoria de WASM de Go 1.26 - cambios en el tiempo de ejecución que afectan a WASI

Versiones de Stack: Esta página fue escrita para Go 1.26.x (Green Tea GC por defecto, go fix modernizers - verifica el parche en la compilación), chi (última versión - verifica en la compilación), gin (última versión - verifica en la compilación), echo (última versión - verifica en la compilación), google.golang.org/grpc (última versión - verifica en la compilación), sigs.k8s.io/controller-runtime (última versión - verifica en la compilación), kubebuilder (última versión - verifica en la compilación), tinygo (última versión - verifica los objetivos de placa en la compilación), wazero (última versión - verifica en la compilación), y golangci-lint (última versión - verifica el conjunto de linters en la compilación).