Boas Práticas da Toolchain
Resumo condensado das 25 práticas de toolchain mais importantes extraídas de cada página desta seção.
//
Busque em todas as páginas da documentação
Resumo condensado das 25 práticas de toolchain mais importantes extraídas de cada página desta seção.
Fixe Agave 4.1.1 em todo lugar: Use agave-install init 4.1.1 para CLI reportar 3.0.10 em laptops e CI (Visão Geral da Toolchain).
Commite rust-toolchain.toml: Trave Rust 1.91.1 com componentes rustfmt, clippy e rust-analyzer (Configuração de Editor e rust-analyzer).
Use avm por repo: Execute avm use 0.32.1 ao entrar em workspaces Anchor - drift global do Anchor quebra builds IDL (Gerenciamento de Versão).
Alinhe crate anchor-lang à CLI: anchor-lang = "0.32.1" deve corresponder à CLI Anchor 0.32.1.
Verifique ordem PATH: which solana deve resolver para install Agave, não binários Homebrew obsoletos.
Documente install no README: Novos contratados copiam um bloco de script - Agave, avm, rustup, Node para clients.
CI imprime versões primeiro: Falhe rápido quando solana --version ou anchor --version não corresponderem pins do manifest.
Cache diretórios toolchain: Chaveie caches Agave e cargo registry em strings de versão para velocidade de pipeline.
Builds release para deploy: cargo build-sbf --release / anchor build antes de qualquer upload devnet ou mainnet (Construindo Programas).
Rastreie tamanho .so no CI: Registre wc -c target/deploy/*.so para detectar regressões binárias cedo.
Um scaffold por produto: Escolha create-solana-dapp, mucho ou manual - evite misturar templates (create-solana-dapp, Mucho CLI).
Atualize @solana/kit explicitamente: package.json client deve fixar 7.0.0 independentemente de Agave.
Execute solana-verify antes da mainnet: Publique hashes locais e on-chain correspondentes para governança (Verifiable Builds).
Deploy apenas artefatos do pipeline verify: Nunca envie builds ad-hoc de laptop para program IDs de produção.
Fixe Surfpool 0.12.0 para dev fork: Documente junto ao Agave quando times simulam estado mainnet.
Fixe LiteSVM 0.6.x em crates de teste: Testes unitários rápidos permanecem consistentes entre máquinas.
Compartilhe .vscode/settings.json: linkedProjects e format-on-save reduzem confusão de macro.
Abra raiz workspace na IDE: Abra pasta contendo Anchor.toml, não apenas subcrates programs/* isolados.
Clean target em upgrades toolchain: cargo clean após bumps de versão Agave ou Anchor.
Trave Cargo.lock para programas: Builds reproduzíveis exigem lockfiles commitados em repos de programa.
Evite Rust nightly para programas: Stable 1.91.1 corresponde expectativas platform tools.
Separe toolchains Node e Rust: nvm/fnm para frontend; rustup para programas - documente ambos.
Automatize checagens doctor: Script gates de versão em pnpm doctor ou make check-tools para workshops.
Anuncie upgrades toolchain: Entrada changelog com checklist re-test antes de bump team-wide.
Mantenha platform tools em bundle: Instale bundle Agave holisticamente - cópias parciais perdem cargo-build-sbf.
Agave 4.1.1, Anchor 0.32.1, Rust 1.91.1, @solana/kit 7.0.0 nos respectivos arquivos de config.
Verifiable builds e lockfiles impedem injeção de dependência não declarada em bytecode deployado.
Docker ajuda CI; desenvolvedores ainda se beneficiam de Agave local para solana logs e iteração deploy.
Em releases de segurança ou features necessárias - nunca flutue latest automaticamente em pipelines produção.
Skew proc-macro / anchor-lang e PATH platform tools - execute anchor test completo após todo bump.
Versões da stack: Esta página foi 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 e LiteSVM 0.6.x.
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026