go build, run, install & clean

Estes quatro comandos cobrem como o Go transforma código-fonte em binários, os executa localmente, instala ferramentas globalmente e redefine caches ao depurar compilações desatualizadas.

Resumo

go build compila pacotes em artefatos que você envia.

go run é um atalho de desenvolvimento que compila para um arquivo temporário e o executa imediatamente.

go install coloca binários de comando no seu PATH via GOBIN ou GOPATH/bin.

go clean remove saídas de compilação e entradas de cache quando você precisa de uma reconstrução a frio.

Todos os quatro compartilham o mesmo carregador de pacotes e honram tags de compilação, GOOS, GOARCH e configurações de módulos.

Receita

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

# Compila um binário de serviço com flags focadas em tamanho
go build -trimpath -ldflags="-s -w" -o bin/api ./cmd/api
 
# Executa localmente com argumentos
go run ./cmd/api --addr :8080
 
# Instala uma ferramenta CLI na versão do módulo em go.mod
go install golang.org/x/tools/cmd/goimports@latest
 
# Limpa o cache de resultados de teste após corrigir um teste instável
go clean -testcache

Quando usar isso:

• Use go build para artefatos de release, imagens Docker e binários de CI.
• Use go run para iteração rápida em pacotes main.
• Use go install para ferramentas de desenvolvedor (goimports, staticcheck, CLIs de geração de código).
• Use go clean -cache apenas ao diagnosticar acertos de cache corrompidos ou impossíveis.

Exemplo de Trabalho

# Layout do módulo:
# .
# ├── go.mod
# ├── cmd/seed/main.go
# └── internal/seed/seed.go
 
go build -o bin/seed ./cmd/seed
./bin/seed --count 5
 
go run ./cmd/seed --count 3
 
go install ./cmd/seed   # instala em $(go env GOPATH)/bin ou GOBIN
 
go clean -i ./cmd/seed  # remove o binário instalado para este caminho de importação

// cmd/seed/main.go
package main
 
import (
    "flag"
    "fmt"
    "example.com/tooldemo/internal/seed"
)
 
func main() {
    n := flag.Int("count", 1, "registros a serem criados")
    flag.Parse()
    fmt.Println(seed.Generate(*n))
}

// internal/seed/seed.go
package seed
 
import "fmt"
 
func Generate(n int) string {
    return fmt.Sprintf("gerados %d registros", n)
}

O que isso demonstra:

• go build -o nomeia a saída explicitamente para scripts de implantação.
• go run aceita o mesmo caminho de pacote e encaminha flags após -- quando necessário.
• go install com um ./cmd/seed relativo instala a partir do módulo atual sem um go get separado.
• go clean -i remove o binário instalado correspondente ao caminho de importação desse pacote.

Mergulho Profundo

Como Funciona

• O carregador resolve o padrão do pacote para um caminho de importação, aplica restrições de compilação e constrói um grafo de ações.
• Etapas de compilação gravam arquivos de arquivo no GOCACHE; etapas de link combinam arquivos de arquivo em executáveis.
• go run vincula a um executável temporário no diretório temporário do sistema operacional e o exclui após a saída (a menos que -work deixe intermediários para inspeção).
• go install pula a cópia para o diretório atual; ele apenas atualiza o destino da instalação.

Flags de Compilação em Destaque

Alvos do go clean

Notas do Go

# Inspeciona onde os artefatos vão
go env GOCACHE GOMODCACHE GOPATH GOBIN
 
# Imprime o ID de compilação invocado pelo linker embutido em binários
go tool buildid bin/seed

Armadilhas

• Usar go run em scripts de produção - compila a cada invocação e oculta o caminho do artefato. Correção: go build uma vez, execute o binário.
• Esquecer -o em CI - nomes de saída padrão colidem ao compilar vários comandos em um único diretório. Correção: sempre defina -o bin/<nome>.
• go install sem uma versão fora de um módulo - @latest pode ultrapassar os pins de CI. Correção: execute a partir de um módulo com um require registrado ou fixe @v1.2.3.
• go clean -modcache em CI compartilhado - força o re-download completo e retarda todos os trabalhos. Correção: cacheie GOMODCACHE entre as execuções; limpe apenas em erros de corrupção.
• Compilação cruzada de pacotes cgo - requer uma toolchain C cruzada, não apenas GOOS/GOARCH. Correção: desabilite cgo (CGO_ENABLED=0) ou instale o compilador cruzado correspondente.
• Expectativas desatualizadas de -trimpath - panics ainda incluem nomes de funções; apenas caminhos de arquivo são cortados. Correção: envie símbolos separadamente se precisar de depuração em nível de caminho.

Alternativas

FAQs

Relacionados

• O Comando go: Ciclo de Vida de Build, Teste e Módulos - grafo de ações e caches
• Noções Básicas da Toolchain Go - exemplos de comandos introdutórios
• Tags de Compilação e Compilação Condicional - fontes protegidas por tags
• Compilação Cruzada e Proxies de Módulos Privados - matriz GOOS/GOARCH
• Melhores Práticas da Toolchain Go - builds reproduzíveis de release

Versões de Stack: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, go fix modernizadores - 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).