go mod tidy, vendor, download & graph

Los comandos de mantenimiento de módulos mantienen go.mod honesto, calientan las cachés, empaquetan fuentes para compilaciones sin conexión y visualizan por qué una versión prevaleció sobre otra.

Resumen

go mod tidy alinea las directivas require con las importaciones realmente referenciadas en tu módulo.

go mod download descarga módulos a GOMODCACHE sin compilarlos.

go mod vendor copia las fuentes de los módulos requeridos a vendor/ para compilaciones con -mod=vendor.

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

Úsalos después de cambios en las dependencias, antes de las ramas de lanzamiento y al depurar la selección de versiones.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

# Normalizar requires después de una refactorización
go mod tidy
 
# Calentar la caché de módulos en CI sin compilar
go mod download all
 
# Materializar fuentes para compilaciones aisladas o auditadas
go mod vendor
 
# Inspeccionar los bordes de requisitos (pares módulo@versión)
go mod graph | head

Cuándo usar esto:

• Ejecuta go mod tidy en cada PR que agregue o elimine importaciones.
• Ejecuta go mod download como un paso temprano de CI con una GOMODCACHE cacheada.
• Ejecuta go mod vendor cuando la política requiera revisar fuentes de terceros en el repositorio.
• Canaliza go mod graph a herramientas de grafos cuando expliques una versión transitiva sorprendente.

Ejemplo de Trabajo

# Empezar desde un módulo que importa x/sync
go get golang.org/x/sync@v0.10.0
 
# Agregar una importación en el código, eliminar otra, y luego hacer tidy
go mod tidy
 
# Pre-cargar todo lo que la lista de compilación necesita
go mod download all
 
# Empaquetar para el trabajo de CI de -mod=vendor
go mod vendor
 
# Compilar usando solo vendor/ + stdlib
go build -mod=vendor -o bin/worker ./cmd/worker
 
# Ver por qué aparece v0.10.0
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()
}

Lo que esto demuestra:

• go get registra una versión; tidy elimina cualquier cosa que ya no se importe.
• download puebla GOMODCACHE para compilaciones posteriores más rápidas.
• vendor más compilaciones con -mod=vendor sin contactar a los proxies de módulos.
• go mod graph ayuda a auditar los bordes después de las actualizaciones.

Inmersión Profunda

Cómo Funciona

• tidy carga todos los paquetes del módulo, recorre las importaciones y reescribe los bloques require de go.mod al conjunto mínimo en las versiones elegidas.
• También actualiza go.sum con los hashes para los módulos directos e indirectos retenidos.
• download resuelve la lista de compilación y copia los archivos .zip en la caché de módulos; no se compilan archivos .a.
• vendor repite la descarga y luego extrae las fuentes bajo vendor/<module>/, reescribiendo go.mod con un marcador de comentario opcional go mod vendor.

Referencia de Comandos

Flujo de Trabajo de Vendor

# Típico pipeline regulado
go mod tidy
go mod vendor
git add go.mod go.sum vendor/
go test -mod=vendor ./...

Graph y Por Qué

# Explicar una versión seleccionada
go mod why -m golang.org/x/sync
 
# Lista de módulos JSON para herramientas SBOM
go list -m -json all

Trampas

• Confirmar tidy sin pruebas - los require eliminados pueden ocultar compilaciones rotas en paquetes no utilizados. Solución: go test ./... después de cada tidy.
• Desviación de vendor - editar go.mod sin volver a empaquetar rompe las CI con -mod=vendor. Solución: automatizar go mod vendor en el mismo commit que los incrementos de dependencias.
• Árboles de vendor/ enormes en bibliotecas - los consumidores rara vez quieren tus copias. Solución: empaquetar en aplicaciones; publicar bibliotecas sin vendor/ a menos que la política lo exija.
• Asumir que download compila - solo descarga zips; los errores de compilación aparecen más tarde en go build. Solución: seguir la descarga con go test en CI.
• Ignorar fallos de go mod verify - indica manipulación de caché o go.sum incompleto. Solución: investigar los mirrors del proxy; no eliminar las sumas a ciegas.
• Ruido indirecto en go.mod - Go 1.17+ marca los require indirectos; tidy mantiene los necesarios para MVS. Solución: confía en tidy; usa go mod why en lugar de editar manualmente.

Alternativas

Preguntas Frecuentes

Relacionado

• El Comando go: Ciclo de Vida de Compilación, Prueba y Módulos - MVS y lista de compilación
• Fundamentos de la Cadena de Herramientas de Go - primer ejemplo de go mod tidy
• Compilación Cruzada y Proxies de Módulos Privados - GOPRIVATE y proxies
• go build, run, install & clean - compilaciones con -mod=vendor
• Mejores Prácticas de la Cadena de Herramientas de Go - higiene de dependencias en CI

Versiones 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 - verificar en la compilación), gin (última - verificar en la compilación), echo (última - verificar en la compilación), google.golang.org/grpc (última - verificar en la compilación), sigs.k8s.io/controller-runtime (última - verificar en la compilación), kubebuilder (última - verificar en la compilación), tinygo (última - verificar objetivos de placa en la compilación), wazero (última - verificar en la compilación), y golangci-lint (última - verificar conjunto de linters en la compilación).