go.mod, go.sum e Seleção de Versão Mínima
go.mod declara seu módulo e suas dependências; go.sum trava seus checksums.
//
Busque em todas as páginas da documentação
go.mod declara seu módulo e suas dependências; go.sum trava seus checksums.
Juntos, eles proporcionam builds reproduzíveis, e a Seleção de Versão Mínima (MVS) escolhe versões compatíveis sem o comportamento arbitrário de "o mais novo vence".
go.mod é o contrato de dependência autoritativo para um módulo.
go.sum registra hashes h1 de arquivos de archive de módulos e go.mod que a toolchain viu.
MVS lê cada requisito no grafo e seleciona a versão mínima semver que ainda os satisfaz a todos.
Entender essas três partes explica a maioria das perguntas sobre go get, desvios de CI e "por que essa versão está aqui?".
Cartão de referência rápida - pronto para copiar e colar.
go mod init example.com/app
go get github.com/stretchr/testify@v1.9.0
go mod tidy
go list -m all// go.mod (após tidy)
module example.com/app
go 1.26
require (
github.com/stretchr/testify v1.9.0
)Quando usar isso:
require não utilizadas após um refatoramento (go mod tidy).example.com/app/
go.mod
go.sum
main.go
// main.go
package main
import (
"fmt"
"github.com/google/uuid"
)
func main() {
fmt.Println(uuid.NewString())
}go get github.com/google/uuid@v1.6.0
go mod tidy
cat go.mod
grep uuid go.sumO que isso demonstra:
require registra dependências diretas que você importa (e às vezes ferramentas).go.sum ganha linhas como github.com/google/uuid v1.6.0 h1:... para verificação de conteúdo.go list -m all mostra módulos diretos e transitivos na lista de build.go get).go carrega os arquivos go.mod do seu módulo e das dependências recursivamente.require.go.sum; linhas ausentes podem ser adicionadas na primeira busca confiável.MVS não é um resolvedor global que minimiza upgrades totais.
É local por caminho de módulo: escolhe a versão mais antiga que ainda atende a todos os mínimos declarados.
| Diretiva | Propósito |
|---|---|
module | Prefixo do caminho de importação para este módulo |
go | Versão mínima da toolchain/linguagem Go |
require | Caminho do módulo → semver (ou pseudo-versão) |
exclude | Impede a seleção de uma versão ruim específica |
replace | Substitui a origem ou versão (caminho local, fork) |
retract | Marca suas próprias releases ruins (no go.mod do seu módulo) |
Dependências indiretas aparecem com comentários // indirect após go mod tidy quando você não as importa diretamente.
Cada versão de módulo tipicamente tem:
github.com/foo/bar v1.2.3 h1:<hash>
github.com/foo/bar v1.2.3/go.mod h1:<hash>
A linha /go.mod faz o hash do próprio arquivo go.mod da dependência.
Faça commit de go.sum para aplicações e bibliotecas para que a CI verifique o mesmo conteúdo.
Se o módulo A requer C v1.2.0 e o módulo B requer C v1.4.0, MVS seleciona C v1.4.0 (o mínimo que satisfaz o requisito mais alto).
Se ambos requeressem v1.2.0, você obteria v1.2.0 mesmo quando v1.9.0 existisse no proxy.
# Veja por que um módulo aparece
go mod why -m github.com/some/transitive
# Grafo de requisitos
go mod graph | head
# Verifique sums sem rede quando possível
go mod verify// diretiva toolchain (opcional, Go 1.21+)
// go.mod
module example.com/app
go 1.26
toolchain go1.26.0go.mod manualmente sem go mod tidy deixa requires órfãos. Prefira comandos que atualizam go.mod e go.sum.go get -u sempre ajuda pode introduzir upgrades amplos; revise diffs e execute testes.go.sum para "corrigir" erros remove o rastro de auditoria; regenere com tidy e gets intencionais em vez disso.// indirect não significa não utilizado - significa que nenhum pacote no seu módulo o importa diretamente; você ainda pode precisar dele transitivamente.GOPRIVATE e credenciais VCS - o banco de dados de checksum pode ser ignorado para caminhos privados.go mod vendor) - Coloca o código fonte em vendor/ para CI offline ou hermética.go.work) - Substituições locais sem fazer commit de replace em todos os módulos.go get module@v em CI - Atualizações roteirizadas em vez de usar @latest em main.Um algoritmo que escolhe, para cada caminho de módulo, a versão semver mais baixa que satisfaz todas as diretivas require no grafo combinado.
Não para projetos em equipe.
Ignore apenas em experimentos descartáveis; repositórios de produção fazem commit dele.
Uma dependência direta importa outro módulo que você não importa.
Tidy o registra para que os builds permaneçam reproduzíveis.
Verifica árvores de módulos em cache e sums contra go.sum.
Execute em CI para detectar corrupção de cache ou adulteração.
go get github.com/foo/bar@v1.1.0 e então teste e faça commit do diff de go.mod/go.sum.
Apenas quando explicitamente requisitado ou quando nenhuma versão estável satisfaz as restrições.
Prefira tags estáveis para produção.
Um log público (sum.golang.org) espelhando hashes de módulos para módulos abertos.
Módulos privados definem GOPRIVATE para ignorá-lo.
O build do seu módulo mescla o grafo; MVS resolve para versões compatíveis ou falha com um erro durante o carregamento.
Recursos de linguagem e comportamento da toolchain disponíveis ao construir este módulo.
Não é uma dependência de runtime como apenas os motores npm.
Após merges que tocam imports, antes de tags de release e em CI a cada PR.
Versões da Stack: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, modernizadores go fix - verifique o patch na build), chi (latest - verifique na build), gin (latest - verifique na build), echo (latest - verifique na build), google.golang.org/grpc (latest - verifique na build), sigs.k8s.io/controller-runtime (latest - verifique na build), kubebuilder (latest - verifique na build), tinygo (latest - verifique os alvos de placa na build), wazero (latest - verifique na build) e golangci-lint (latest - verifique o conjunto de linters na build).
Revisado por Chris St. John·Última atualização: 18 de jul. de 2026