Compilando com GOOS=wasip1 GOARCH=wasm

O target WASI do Go transforma pacotes comuns em módulos .wasm portáteis.

O comando de compilação espelha a compilação cruzada para Linux ou Windows - defina GOOS e GOARCH, e então go build.

Entender quais flags importam, e quais arquivos (wasm_exec.js) pertencem a um target diferente, mantém seus scripts de build e matrizes de CI corretos.

Resumo

GOOS=wasip1 com GOARCH=wasm seleciona a superfície de chamadas de sistema WASI Preview 1.

O linker do Go emite um módulo importando funções wasi_snapshot_preview1 em vez de chamadas de sistema específicas da plataforma.

Você executa o artefato com um host WASM externo (wasmtime, wazero, Spin) em vez do comando go.

Builds de lançamento comumente passam -ldflags="-s -w" para remover metadados de depuração.

Notas sobre wasm_exec.js para targets de navegador não se aplicam à saída wasip1.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

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

Quando usar isso:

• Ferramentas CLI portáteis distribuídas como um único artefato .wasm
• Plugins com sandbox executados dentro de um serviço Go via wazero
• Funções de edge em Spin/Fermyon ou hosts WASM compatíveis
• Builds verificados por CI que não devem depender de binários nativos do SO
• Lógica de negócios compartilhada compilada uma vez e incorporada em múltiplos aplicativos host

Exemplo de Trabalho

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
# salve main.go, então:
GOOS=wasip1 GOARCH=wasm go build -ldflags="-s -w" -o greet.wasm .
wasmtime run --env CONFIG_JSON='{"name":"Ada"}' greet.wasm

O que isso demonstra:

• Pacotes da biblioteca padrão (encoding/json, os) compilam para WASI sem tags.
• Variáveis de ambiente são capacidades fornecidas pelo host (--env no wasmtime).
• Códigos de saída se propagam para o processo host como um CLI nativo.
• Saída de erro em os.Stderr mapeia para streams stderr do host.

Mergulho Profundo

Como Funciona

• O compilador Go reduz goroutines e GC para instruções WASM mais imports de runtime.
• wasip1 mapeia operações de arquivo os para APIs fd WASI que o host deve implementar.
• A exportação _start é o ponto de entrada que o host chama após instanciar a memória linear.
• go mod e vendoring funcionam da mesma forma que builds nativos; cgo não está disponível neste target.

Referência do Ambiente de Build

wasm_exec.js vs WASI

Não copie GOROOT/misc/wasm/wasm_exec.js para pacotes de implantação WASI.

Notas do Go

// Arquivos de entrada separados para navegador - nunca compile estes em builds wasip1.
//go:build js && wasm
 
package browseronly

# Padrão Makefile
build-wasi:
	GOOS=wasip1 GOARCH=wasm go build -ldflags="-s -w" -o bin/app.wasm ./cmd/app

Armadilhas

• Assumir que go run funciona - Não há emulador WASI dentro de go run; você deve executar com um host WASM. Correção: envolva wasmtime run ou wazero em alvos go:generate/Makefile.

• Escritas de sistema de arquivos sem pré-abertura - os.Create("/tmp/x") falha se o host não mapeou /tmp. Correção: passe wasmtime run --dir /host/tmp::/tmp ou configure wazero FSConfig.

• Misturar arquivos js/wasm em pacotes WASI - Imports acidentais de syscall/js quebram a compilação wasip1. Correção: isole o código do navegador por trás de tags de build js && wasm.

• Esperar rede completa - WASI preview 1 não garante APIs TCP em todos os runtimes. Correção: confirme o suporte a sockets ou use gatilhos HTTP do Spin.

• Binários enormes por surpresa - O runtime Go completo adiciona megabytes mesmo para fmt.Println. Correção: meça o tamanho cedo; considere TinyGo ou divida os caminhos quentes.

• GOOS=wasi obsoleto - Documentação mais antiga referencia wasi; toolchains modernas usam wasip1. Correção: atualize scripts para wasip1 para Go 1.21+.

Alternativas

FAQs

Relacionado

• Go em WebAssembly: Caminhos para Navegador, WASI e Embutidos - visão geral de três caminhos
• Runtimes Host WASI: wasmtime, wazero & Spin - execute e incorpore módulos
• syscall/js: Go no Navegador - quando você precisa de js/wasm em vez disso
• Otimização de Tamanho WASM: TinyGo vs gc WASM - táticas de linker e importação
• Melhorias no Runtime e Memória WASM do Go 1.26 - mudanças no runtime que afetam WASI

Versões da Stack: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, go fix modernizers - verifique o patch no build), chi (latest - verifique no build), gin (latest - verifique no build), echo (latest - verifique no build), google.golang.org/grpc (latest - verifique no build), sigs.k8s.io/controller-runtime (latest - verifique no build), kubebuilder (latest - verifique no build), tinygo (latest - verifique os targets de placa no build), wazero (latest - verifique no build) e golangci-lint (latest - verifique o conjunto de linters no build).