Restricciones de Compilación y Archivos Específicos de Plataforma
Las restricciones de compilación le indican a la toolchain de Go qué archivos fuente pertenecen a una compilación determinada.
//
Busca en todas las páginas de la documentación
Las restricciones de compilación le indican a la toolchain de Go qué archivos fuente pertenecen a una compilación determinada.
Las expresas con líneas //go:build, sufijos de archivo y etiquetas personalizadas pasadas a través de -tags.
El resultado es un único árbol de módulos que compila diferentes implementaciones por sistema operativo, arquitectura o bandera de característica.
Antes de Go 1.17, las restricciones usaban líneas de comentario // +build.
El código moderno debe usar //go:build como la primera línea de un archivo (opcionalmente seguida por una línea en blanco y el paquete).
La toolchain evalúa las restricciones contra GOOS, GOARCH y etiquetas personalizadas.
Los archivos sin restricciones siempre se incluyen; los archivos específicos de plataforma deben proporcionar alternativas o vivir solo detrás de las etiquetas coincidentes.
Tarjeta de receta de referencia rápida - lista para copiar y pegar.
//go:build linux && amd64
package sysfs
// Implementación linux_amd64go build -tags=integration ./...
GOOS=windows GOARCH=arm64 go build ./...Cuándo usar esto:
syscall, x/sys) sin la proliferación de if runtime.GOOS en tiempo de ejecución.example.com/net/
listen.go
listen_unix.go
listen_windows.go
// listen.go - todas las 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 a diferencia de 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())
}Lo que esto demuestra:
unix es una etiqueta predefinida que cubre Linux, BSD, macOS y otros valores de GOOS similares a Unix.go build recopila todos los archivos .go en el directorio del paquete.GOOS, GOARCH y -tags forman el entorno de evaluación.| Término | Significado |
|---|---|
valor GOOS | linux, windows, darwin, freebsd, ... |
valor GOARCH | amd64, arm64, wasm, ... |
unix | Plataformas similares a Unix (ver go tool dist list) |
gc / gccgo | Toolchain del compilador |
cgo | cgo habilitado para esta compilación |
| Patrón de sufijo | Restricción implícita |
|---|---|
_linux.go | GOOS=linux |
_windows.go | GOOS=windows |
_amd64.go | GOARCH=amd64 |
_linux_amd64.go | linux Y amd64 |
Las reglas de sufijo se combinan con las líneas //go:build explícitas cuando ambas están presentes.
//go:build (linux || darwin) && amd64
//go:build !windows
//go:build integration && !short
Use paréntesis para la precedencia.
go list -tags=integration -f '{{.GoFiles}}' ./...Inspeccione los archivos seleccionados antes de depurar errores de compilación de "símbolo indefinido".
linux deja a otros GOOS sin las funciones requeridas. Solución: agregue default.go o un archivo !linux con código portable.runtime.GOOS en lugar de etiquetas - compila importaciones prohibidas en otras plataformas. Solución: mueva las importaciones detrás de archivos etiquetados por compilación._foo.go más //go:build conflictivo confunde a los lectores. Solución: prefiera un estilo por archivo.linux/amd64 oculta archivos de Windows rotos. Solución: compile cruzado GOOS=windows en CI como mínimo.go test sin -tags y omiten suites silenciosamente. Solución: documente las etiquetas en Makefile y README.// +build heredado - todavía funciona, pero gofmt lo reescribe a //go:build en toolchains modernas. Solución: migre al tocar.| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
Cambio runtime.GOOS | Diferencias de comportamiento pequeñas, sin importaciones especiales | El archivo necesita importaciones solo del SO |
| Paquetes separados por plataforma | Implementaciones grandes y divergentes | Deltas simples de una función |
| Etiquetas de compilación WASM/navegador | Puntos de entrada específicos de JS | Código solo del servidor |
| Etiquetas de compilación para características | Módulos opcionales de pago/empresariales | Las simples alternancias de configuración son mejores como flags en tiempo de ejecución |
La línea de restricción debe aparecer antes de la cláusula package (solo comentarios y líneas en blanco pueden precederla).
Las etiquetas se aplican a las fuentes .go.
Use archivos embed o de assets separados con archivos Go etiquetados que hagan referencia a ellos.
Patrón común: //go:build integration && !short para que go test -short por defecto omita las pruebas lentas.
Las etiquetas se aplican por invocación.
go build y go test necesitan el mismo -tags cuando espera conjuntos de archivos idénticos.
Sí.
//go:build cgo selecciona archivos solo cuando cgo está habilitado para la compilación.
Los objetivos móviles usan valores GOOS como ios y android con sus propios conjuntos de etiquetas.
Verifique con go tool dist list para su versión de Go.
Ejecute go list -f '{{.GoFiles}} {{.IgnoredGoFiles}}' ./package para ver las fuentes ignoradas.
Sí.
Los archivos _test.go siguen las mismas reglas de restricción de compilación que los archivos de producción.
Solo una línea de restricción //go:build (posiblemente con operadores booleanos).
No apile múltiples comentarios de restricción separados.
Las etiquetas se aplican por compilación de módulo dentro del workspace.
Los archivos etiquetados de cada módulo se evalúan de forma independiente.
.s específicos de arquitecturaVersiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado Green Tea GC, go fix modernizers - verificar parche en la compilación), chi (última versión - verificar en la compilación), gin (última versión - verificar en la compilación), echo (última versión - verificar en la compilación), google.golang.org/grpc (última versión - verificar en la compilación), sigs.k8s.io/controller-runtime (última versión - verificar en la compilación), kubebuilder (última versión - verificar en la compilación), tinygo (última versión - verificar objetivos de placa en la compilación), wazero (última versión - verificar en la compilación), y golangci-lint (última versión - verificar conjunto de linters en la compilación).
Revisado por Chris St. John·Última actualización: 16 jul 2026