Mejores Prácticas de Toolchain
Un resumen condensado de las 25 prácticas de toolchain más importantes extraídas de todas las páginas de esta sección.
//
Busca en todas las páginas de la documentación
Un resumen condensado de las 25 prácticas de toolchain más importantes extraídas de todas las páginas de esta sección.
Fijar Agave 4.1.1 en todas partes: Usa agave-install init 4.1.1 para que la CLI informe 3.0.10 en portátiles y CI (Descripción General de Toolchain).
Confirmar rust-toolchain.toml: Bloquea Rust 1.91.1 con los componentes rustfmt, clippy y rust-analyzer (Configuración del Editor y rust-analyzer).
Usar avm por repositorio: Ejecuta avm use 0.32.1 al entrar en espacios de trabajo de Anchor; la deriva global de Anchor rompe las compilaciones de IDL (Gestión de Versiones).
Alinear la crate anchor-lang con la CLI: anchor-lang = "0.32.1" debe coincidir con Anchor CLI 0.32.1.
Verificar el orden de PATH: which solana debe resolverse a la instalación de Agave, no a binarios obsoletos de Homebrew.
Documentar la instalación en README: Los nuevos miembros del equipo copian un bloque de script: Agave, avm, rustup, Node para clientes.
La CI imprime las versiones primero: Falla rápidamente cuando solana --version o anchor --version muestran discrepancias con las versiones fijadas.
Caché de directorios de toolchain: Clave las cachés de Agave y del registro de cargo por cadenas de versión para acelerar el pipeline.
Compilaciones de lanzamiento para despliegue: cargo build-sbf --release / anchor build antes de cualquier carga a devnet o mainnet (Compilación de Programas).
Rastrear el tamaño de .so en CI: Registra wc -c target/deploy/*.so para detectar regresiones binarias tempranamente.
Un scaffold por producto: Elige create-solana-dapp, mucho o manual; evita mezclar plantillas (create-solana-dapp, Mucho CLI).
Incrementar @solana/kit explícitamente: El package.json del cliente debe fijar 7.0.0 independientemente de Agave.
Ejecutar solana-verify antes de mainnet: Publica hashes locales y en cadena coincidentes para la gobernanza (Compilaciones Verificables).
Desplegar solo artefactos del pipeline de verificación: Nunca cargues compilaciones ad-hoc del portátil a los IDs de programa de producción.
Fijar Surfpool 0.12.0 para desarrollo de forks: Documentar junto con Agave cuando los equipos simulan el estado de mainnet.
Fijar LiteSVM 0.6.x en crates de prueba: Las pruebas unitarias rápidas se mantienen consistentes entre máquinas.
Compartir .vscode/settings.json: linkedProjects y format-on-save reducen la confusión de macros.
Abrir la raíz del espacio de trabajo en el IDE: Abre la carpeta que contiene Anchor.toml, no solo subcrates aisladas de programs/*.
Limpiar target en actualizaciones de toolchain: cargo clean después de cambios de versión de Agave o Anchor.
Bloquear Cargo.lock para programas: Las compilaciones reproducibles requieren archivos de bloqueo confirmados en los repositorios de programas.
Evitar Rust nightly para programas: Estable 1.91.1 coincide con las expectativas de las herramientas de plataforma.
Separar toolchains de Node y Rust: nvm/fnm para frontend; rustup para programas - documentar ambos.
Automatizar comprobaciones de doctor: Script de puertas de versión en pnpm doctor o make check-tools para talleres.
Anunciar actualizaciones de toolchain: Entrada en el changelog con lista de verificación de re-test antes de la actualización para todo el equipo.
Mantener las herramientas de plataforma empaquetadas: Instalar el paquete de Agave de forma integral; las copias parciales omiten cargo-build-sbf.
Agave 4.1.1, Anchor 0.32.1, Rust 1.91.1, @solana/kit 7.0.0 en sus respectivos archivos de configuración.
Las compilaciones verificables y los archivos de bloqueo previenen la inyección de dependencias no declaradas en el bytecode desplegado.
Docker ayuda a la CI; los desarrolladores aún se benefician de Agave local para solana logs e iteración de despliegue.
En lanzamientos de seguridad o características necesarias; nunca usar latest automáticamente en pipelines de producción.
La desincronización de proc-macro / anchor-lang y el PATH de las herramientas de plataforma; ejecuta anchor test completo después de cada actualización.
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.
Revisado por Chris St. John·Última actualización: 16 jul 2026