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.

1. 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).

2. Confirmar rust-toolchain.toml: Bloquea Rust 1.91.1 con los componentes rustfmt, clippy y rust-analyzer (Configuración del Editor y rust-analyzer).

3. 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).

4. Alinear la crate anchor-lang con la CLI: anchor-lang = "0.32.1" debe coincidir con Anchor CLI 0.32.1.

5. Verificar el orden de PATH: which solana debe resolverse a la instalación de Agave, no a binarios obsoletos de Homebrew.

6. Documentar la instalación en README: Los nuevos miembros del equipo copian un bloque de script: Agave, avm, rustup, Node para clientes.

7. La CI imprime las versiones primero: Falla rápidamente cuando solana --version o anchor --version muestran discrepancias con las versiones fijadas.

8. 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.

9. Compilaciones de lanzamiento para despliegue: cargo build-sbf --release / anchor build antes de cualquier carga a devnet o mainnet (Compilación de Programas).

10. Rastrear el tamaño de .so en CI: Registra wc -c target/deploy/*.so para detectar regresiones binarias tempranamente.

11. Un scaffold por producto: Elige create-solana-dapp, mucho o manual; evita mezclar plantillas (create-solana-dapp, Mucho CLI).

12. Incrementar @solana/kit explícitamente: El package.json del cliente debe fijar 7.0.0 independientemente de Agave.

13. Ejecutar solana-verify antes de mainnet: Publica hashes locales y en cadena coincidentes para la gobernanza (Compilaciones Verificables).

14. Desplegar solo artefactos del pipeline de verificación: Nunca cargues compilaciones ad-hoc del portátil a los IDs de programa de producción.

15. Fijar Surfpool 0.12.0 para desarrollo de forks: Documentar junto con Agave cuando los equipos simulan el estado de mainnet.

16. Fijar LiteSVM 0.6.x en crates de prueba: Las pruebas unitarias rápidas se mantienen consistentes entre máquinas.

17. Compartir .vscode/settings.json: linkedProjects y format-on-save reducen la confusión de macros.

18. Abrir la raíz del espacio de trabajo en el IDE: Abre la carpeta que contiene Anchor.toml, no solo subcrates aisladas de programs/*.

19. Limpiar target en actualizaciones de toolchain: cargo clean después de cambios de versión de Agave o Anchor.

20. Bloquear Cargo.lock para programas: Las compilaciones reproducibles requieren archivos de bloqueo confirmados en los repositorios de programas.

21. Evitar Rust nightly para programas: Estable 1.91.1 coincide con las expectativas de las herramientas de plataforma.

22. Separar toolchains de Node y Rust: nvm/fnm para frontend; rustup para programas - documentar ambos.

23. Automatizar comprobaciones de doctor: Script de puertas de versión en pnpm doctor o make check-tools para talleres.

24. 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.

25. Mantener las herramientas de plataforma empaquetadas: Instalar el paquete de Agave de forma integral; las copias parciales omiten cargo-build-sbf.

Preguntas Frecuentes

Relacionados

• Descripción General de Toolchain - introducción a la pila
• Gestión de Versiones (agave-install / avm) - cómo fijar versiones
• Mejores Prácticas de Solana CLI - operaciones de CLI
• Lista de Verificación de Configuración del Entorno - incorporación de equipos

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.