go mod tidy, vendor, download & graph

Comandos de manutenção de módulos mantêm o go.mod honesto, aquecem caches, preparam fontes para builds offline e visualizam por que uma versão foi escolhida em detrimento de outra.

Resumo

go mod tidy alinha as diretivas require com os imports realmente referenciados no seu módulo.

go mod download busca módulos para o GOMODCACHE sem compilar.

go mod vendor copia as fontes dos módulos necessários para vendor/ para builds com -mod=vendor.

go mod graph imprime o grafo de requisitos de módulos MVS consumido.

Use-os após alterações de dependência, antes de branches de release e ao depurar a seleção de versão.

Receita

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

# Normaliza os requires após um refatoramento
go mod tidy
 
# Aquece o cache de módulos em CI sem compilar
go mod download all
 
# Materializa fontes para builds offline ou auditados
go mod vendor
 
# Inspeciona as arestas de requisitos (pares module@version)
go mod graph | head

Quando usar isso:

• Execute go mod tidy em todo PR que adiciona ou remove imports.
• Execute go mod download como um passo inicial de CI com um GOMODCACHE em cache.
• Execute go mod vendor quando a política exigir a revisão de fontes de terceiros no repositório.
• Redirecione go mod graph para ferramentas de grafo ao explicar uma versão transitiva surpreendente.

Exemplo de Trabalho

# Comece com um módulo que importa x/sync
go get golang.org/x/sync@v0.10.0
 
# Adicione um import no código, remova outro e depois execute tidy
go mod tidy
 
# Pré-carregue tudo que a lista de build precisa
go mod download all
 
# Prepare o vendor para o job de CI com -mod=vendor
go mod vendor
 
# Compile usando apenas vendor/ + stdlib
go build -mod=vendor -o bin/worker ./cmd/worker
 
# Veja por que v0.10.0 aparece
go mod graph | rg 'golang.org/x/sync'

// cmd/worker/main.go
package main
 
import (
    "fmt"
    "golang.org/x/sync/errgroup"
)
 
func main() {
    var g errgroup.Group
    g.Go(func() error { fmt.Println("task"); return nil })
    _ = g.Wait()
}

O que isso demonstra:

• go get registra uma versão; tidy remove qualquer coisa que não seja mais importada.
• download preenche o GOMODCACHE para compilações posteriores mais rápidas.
• vendor mais builds com -mod=vendor sem acessar proxies de módulos.
• go mod graph ajuda a auditar as arestas após atualizações.

Mergulho Profundo

Como Funciona

• tidy carrega todos os pacotes do módulo, percorre os imports e reescreve os blocos require do go.mod para o conjunto mínimo nas versões escolhidas.
• Ele também atualiza o go.sum com hashes para módulos diretos e indiretos retidos.
• download resolve a lista de build e copia arquivos .zip para o cache de módulos; nenhum arquivo .a é compilado.
• vendor repete o download e extrai as fontes em vendor/<module>/, reescrevendo o go.mod com um marcador de comentário opcional go mod vendor.

Referência de Comando

Fluxo de Trabalho de Vendor

# Pipeline regulamentado típico
go mod tidy
go mod vendor
git add go.mod go.sum vendor/
go test -mod=vendor ./...

Grafo e Por Quê

# Explica uma versão selecionada
go mod why -m golang.org/x/sync
 
# Lista de módulos JSON para ferramentas SBOM
go list -m -json all

Armadilhas

• Commitar tidy sem testes - requires podados podem ocultar builds quebrados em pacotes não utilizados. Correção: go test ./... após cada tidy.
• Desvio de vendor - editar go.mod sem re-vendoring quebra o CI com -mod=vendor. Correção: automatize go mod vendor no mesmo commit das atualizações de dependência.
• Árvores vendor/ enormes em bibliotecas - consumidores raramente querem suas cópias. Correção: use vendor em aplicações; publique bibliotecas sem vendor/ a menos que a política exija.
• Assumir que download compila - ele apenas busca zips; erros de compilação aparecem depois em go build. Correção: siga o download com go test em CI.
• Ignorar falhas de go mod verify - indica adulteração de cache ou go.sum incompleto. Correção: investigue espelhos de proxy; não exclua sums cegamente.
• Ruído indireto em go.mod - Go 1.17+ marca requires indiretos; tidy mantém os necessários para MVS. Correção: confie no tidy; use go mod why em vez de editar manualmente.

Alternativas

FAQs

Relacionados

• O Comando go: Ciclo de Vida de Build, Teste e Módulos - MVS e lista de build
• Noções Básicas da Toolchain Go - primeiro exemplo de go mod tidy
• Compilação Cruzada e Proxies de Módulos Privados - GOPRIVATE e proxies
• go build, run, install & clean - builds com -mod=vendor
• Melhores Práticas da Toolchain Go - higiene de dependências em CI

Versões da Pilha: 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).