Build Constraints & Platform-Specific Files
Build constraints informam ao toolchain do Go quais arquivos-fonte pertencem a um determinado build.
//
Busque em todas as páginas da documentação
Build constraints informam ao toolchain do Go quais arquivos-fonte pertencem a um determinado build.
Você os expressa com linhas //go:build, sufixos de arquivo e tags personalizadas passadas via -tags.
O resultado é uma árvore de módulos que compila implementações diferentes por sistema operacional, arquitetura ou flag de recurso.
Antes do Go 1.17, as constraints usavam linhas de comentário // +build.
O código moderno deve usar //go:build como a primeira linha de um arquivo (opcionalmente seguida por uma linha em branco e o pacote).
O toolchain avalia as constraints em relação a GOOS, GOARCH e tags personalizadas.
Arquivos sem constraints são sempre incluídos; arquivos específicos de plataforma devem fornecer fallbacks ou viver apenas atrás de tags correspondentes.
Cartão de receita de referência rápida - pronto para copiar e colar.
//go:build linux && amd64
package sysfs
// Implementação linux_amd64go build -tags=integration ./...
GOOS=windows GOARCH=arm64 go build ./...Quando usar isso:
syscall, x/sys) sem a proliferação de if runtime.GOOS em tempo de execução.example.com/net/
listen.go
listen_unix.go
listen_windows.go
// listen.go - todas as plataformas
package net
func DefaultListenConfig() ListenConfig {
return ListenConfig{}
}
type ListenConfig struct {
ReusePort bool
}// listen_unix.go
//go:build unix
package net
func (c ListenConfig) platformReuse() bool { return c.ReusePort }// listen_windows.go
//go:build windows
package net
func (c ListenConfig) platformReuse() bool { return false } // SO_REUSEPORT diferente do Windows// demo/main.go
package main
import (
"fmt"
"example.com/net"
)
func main() {
cfg := net.DefaultListenConfig()
cfg.ReusePort = true
fmt.Println("reuse supported:", cfg.platformReuse())
}O que isso demonstra:
unix é uma tag predefinida que cobre Linux, BSD, macOS e outros valores GOOS semelhantes ao Unix.go build coleta todos os arquivos .go no diretório do pacote.GOOS, GOARCH e -tags formam o ambiente de avaliação.| Termo | Significado |
|---|---|
Valor GOOS | linux, windows, darwin, freebsd, ... |
Valor GOARCH | amd64, arm64, wasm, ... |
unix | Plataformas semelhantes ao Unix (veja go tool dist list) |
gc / gccgo | Toolchain do compilador |
cgo | cgo habilitado para este build |
| Padrão de sufixo | Constraint implícita |
|---|---|
_linux.go | GOOS=linux |
_windows.go | GOOS=windows |
_amd64.go | GOARCH=amd64 |
_linux_amd64.go | linux E amd64 |
As regras de sufixo se combinam com as linhas //go:build explícitas quando ambas estão presentes.
//go:build (linux || darwin) && amd64
//go:build !windows
//go:build integration && !short
Use parênteses para precedência.
go list -tags=integration -f '{{.GoFiles}}' ./...Inspecione os arquivos selecionados antes de depurar falhas de build de "símbolo indefinido".
linux deixa outros GOOS sem as funções necessárias. Correção: adicione default.go ou um arquivo !linux com código portátil.runtime.GOOS em vez de tags - compila imports proibidos em outras plataformas. Correção: mova imports para arquivos com tags de build._foo.go mais //go:build conflitante confunde os leitores. Correção: prefira um estilo por arquivo.linux/amd64 oculta arquivos quebrados do Windows. Correção: compile cruzado GOOS=windows em CI, no mínimo.go test sem -tags e pulam suítes silenciosamente. Correção: documente as tags no Makefile e README.// +build legado - ainda funciona, mas gofmt o reescreve para //go:build em toolchains modernos. Correção: migre ao tocar.| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
Switch runtime.GOOS | Diferenças comportamentais minúsculas, sem imports especiais | Arquivo precisa de imports específicos do SO |
| Pacotes separados por plataforma | Grandes implementações divergentes | Deltas simples de uma função |
| Tags de build WASM/navegador | Pontos de entrada específicos de JS | Código apenas do servidor |
| Tags de build para recursos | Módulos opcionais pagos/corporativos | Configurações simples são melhores como flags de tempo de execução |
A linha de constraint deve aparecer antes da cláusula package (apenas comentários e linhas em branco podem precedê-la).
Tags se aplicam a fontes .go.
Use árvores de embed ou de assets separadas com arquivos Go com tags que as referenciem.
Padrão comum: //go:build integration && !short para que go test -short padrão pule testes lentos.
Tags se aplicam por invocação.
go build e go test precisam do mesmo -tags quando você espera conjuntos de arquivos idênticos.
Sim.
//go:build cgo seleciona arquivos apenas quando cgo está habilitado para o build.
Alvos móveis usam valores GOOS como ios e android com seus próprios conjuntos de tags.
Verifique com go tool dist list para sua versão do Go.
Execute go list -f '{{.GoFiles}} {{.IgnoredGoFiles}}' ./package para ver fontes ignoradas.
Sim.
Arquivos _test.go seguem as mesmas regras de build constraint que os arquivos de produção.
Apenas uma linha de constraint //go:build (possivelmente com operadores booleanos).
Não empilhe vários comentários de constraint separados.
Tags se aplicam por build de módulo dentro do workspace.
Os arquivos com tags de cada módulo são avaliados independentemente.
.s específicos de arquiteturaVersões da Stack: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, go fix modernizers - verifique o patch na compilação), chi (última versão - verifique na compilação), gin (última versão - verifique na compilação), echo (última versão - verifique na compilação), google.golang.org/grpc (última versão - verifique na compilação), sigs.k8s.io/controller-runtime (última versão - verifique na compilação), kubebuilder (última versão - verifique na compilação), tinygo (última versão - verifique os alvos de placa na compilação), wazero (última versão - verifique na compilação) e golangci-lint (última versão - verifique o conjunto de linters na compilação).
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026