Gestión de Versiones (agave-install / avm)
Fija las versiones de Agave/Solana CLI y Anchor con agave-install y avm para que cada máquina y trabajo de CI compile y despliegue contra el mismo runtime.
Receta
Tarjeta de receta de referencia rápida - lista para copiar y pegar.
agave-install init 4.1.1
solana --version
avm install 0.32.1
avm use 0.32.1
anchor --versionCuándo usar esto:
- Al actualizar el equipo a Agave 4.1.1 / CLI 3.0.10.
- Al cambiar entre repositorios que requieren diferentes versiones de Anchor.
- Al reproducir un entorno de despliegue de producción localmente.
- Al corregir CI después de que una instalación silenciosa de
latestrompiera las compilaciones.
Ejemplo de Trabajo
# Fijar Agave / Solana CLI
sh -c "$(curl -sSfL https://release.anza.xyz/v4.1.1/install)"
agave-install init 4.1.1
solana --version
# Fijar Anchor a través de avm
cargo install --git https://github.com/coral-xyz/anchor avm --locked --force
avm install 0.32.1
avm use 0.32.1
anchor --version
# Anchor.toml por proyecto impone la CLI para comandos de anchor
grep '^anchor_version' Anchor.toml || echo 'anchor_version = "0.32.1"' >> Anchor.tomlLo que esto demuestra:
agave-install initselecciona el canal de lanzamiento del validador/CLI.avm usecambia el binarioanchoren PATH.Anchor.tomlanchor_versionadvierte cuando la falta de coincidencia de la CLI corrompería las compilaciones de IDL.
Análisis Profundo
Cómo Funciona
agave-installdescarga los artefactos de lanzamiento en~/.local/share/solana/install/active_release.- Shell PATH antepone ese directorio
binparasolana,cargo-build-sbf, etc. avmalmacena múltiples compilaciones de Anchor CLI bajo~/.avmy enlaza simbólicamente la activa.- Rust en sí se gestiona por separado a través de
rustup(fija 1.91.1 conrust-toolchain.toml).
Lista de Verificación de Fijación
| Capa | Herramienta | Método de fijación |
|---|---|---|
| Validador/CLI | agave-install | init 4.1.1 |
| Anchor CLI | avm | use 0.32.1 |
crate anchor-lang | Cargo.toml | 0.32.1 |
| Compilador Rust | rustup | rust-toolchain.toml |
Notas de bash
# Listar lanzamientos de Agave instalados
agave-install list
# Listar versiones de Anchor instaladas
avm listTrampas Comunes
- Enmascaramiento de PATH -
solanade Homebrew anula la instalación de Agave. Solución:which solanay reordenar PATH. - avm olvidado en CI - La imagen Docker tiene Anchor 0.30 mientras que el repositorio necesita 0.32.1. Solución: paso explícito de
avm useen el pipeline. - Falta de coincidencia de
anchor-lang- CLI 0.32.1 con crate 0.30.x falla la expansión de macros. Solución: actualizar todos los crates de Anchor juntos. - Actualización a mitad de sprint sin anuncio - rompe las sesiones de emparejamiento. Solución: documentar las actualizaciones en el registro de cambios del equipo.
- Deriva del valor predeterminado estable de
rustup- el nuevo estable rompecargo build-sbf. Solución: confirmarrust-toolchain.tomlcon 1.91.1.
Alternativas
| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
Solo rust-toolchain.toml | Servicios solo de Rust | Fijación completa de Solana CLI |
| Entornos de desarrollo Nix / Docker | Entornos de equipo herméticos | Configuración rápida de portátil individual |
Ayudantes de versión mucho | Repositorios de plantilla de Foundation | Diseños personalizados de múltiples repositorios |
| Extracción manual de tarball | Instalaciones aisladas del aire | Desarrollo normal con conexión a Internet |
Preguntas Frecuentes
¿Reemplaza agave-install a solana-install?
Sí - usa las URLs de lanzamiento de Anza (release.anza.xyz) para Agave 4.x en adelante.
¿Cómo fijo Rust 1.91.1?
Añade rust-toolchain.toml con channel = "1.91.1" en la raíz del repositorio.
¿Pueden dos repositorios usar diferentes versiones de Anchor?
Sí - ejecuta avm use al cambiar de directorio o usa los hooks de direnv.
¿Qué pasa si la compilación de anchor advierte sobre una falta de coincidencia de versión?
Alinea avm use, Anchor.toml anchor_version y la versión del crate anchor-lang a la misma versión.
¿Cómo actualizo Agave de forma segura?
Instala la nueva versión, ejecuta anchor test completo y un despliegue de prueba en devnet, luego actualiza la documentación del equipo.
¿Gestiona avm el crate anchor-lang?
No - solo el binario CLI. Cargo.toml todavía fija las dependencias del programa.
¿Cómo desinstalo versiones antiguas de Agave?
agave-install list luego elimina los directorios no utilizados según la documentación de Anza, o reinstala un canal limpio.
¿Debería CI llamar a agave-install en cada trabajo?
Caché el directorio de instalación con clave de versión 4.1.1 para velocidad; verifica con solana --version en cada ejecución.
¿Qué pasa con la versión de solana-verify?
Instala la versión coincidente junto con Agave al usar pipelines de compilación verificables.
¿Cómo fijo @solana/kit?
Usa package.json "@solana/kit": "7.0.0" - separado de las fijaciones de Agave/Anchor.
Relacionado
- Descripción General de Toolchain - qué hace cada herramienta
- Compilación de Programas (cargo build-sbf) - compilar después de fijar
- Mejores Prácticas de Toolchain - política del equipo
- Configuración del Editor y rust-analyzer - IDE usa la misma fijación de Rust
Versiones de la Pila: Esta página fue escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, y LiteSVM 0.6.x.