Esegui yarn install, e la dipendenza che hai appena aggiornato punta ancora alla vecchia build. O il tuo laptop installa senza problemi mentre la CI fallisce improvvisamente dopo una modifica innocua al lockfile. O le rebuild di Docker si trascinano, anche se stai "usando la cache".
È proprio in quei momenti che le persone cercano Pulizia della cache di Yarn e incollano il primo comando che trovano.
A volte funziona. A volte non risolve nulla. Il motivo è semplice: il comportamento della cache di Yarn dipende molto dalla versione di Yarn che stai usando, e la differenza tra Yarn Classic v1 e Yarn Berry v2+ è una differenza tale da cambiare sia il comando corretto sia la strategia di troubleshooting.
La maggior parte delle guide si ferma a yarn cache clean. Ma è solo l'inizio. Ciò che conta è l'ambito della cache, se il progetto usa una cache locale o condivisa, e se il tuo vero problema sia addirittura la cache. In CI e Docker, una cattiva strategia di caching spesso fa più danni degli archivi di pacchetti obsoleti.
Indice dei contenuti
- La tua build è rotta e la cache di Yarn potrebbe essere la colpevole
- Quando e perché svuotare la cache di Yarn
- Come svuotare la cache in Yarn Classic v1
- Gestione moderna della cache in Yarn Berry v2+
- Best practice per la cache di Yarn in CI/CD e Docker
- Risoluzione dei comuni errori della cache di Yarn
- Domande frequenti sulla pulizia della cache di Yarn
La tua build è rotta e la cache di Yarn potrebbe essere la colpevole
Uno scenario comune è questo: aggiorni un pacchetto, scarichi le ultime modifiche e lanci di nuovo l'install. Il comando termina, ma l'app si comporta ancora come se la vecchia dipendenza fosse presente. Qualcuno suggerisce di svuotare la cache, e ora ti chiedi se sia una soluzione reale o solo superstizione.
Può essere una soluzione reale. Può anche essere una distrazione.
I problemi di cache si manifestano solitamente in pochi modi prevedibili. Un pacchetto locale non si aggiorna. La CI scarica qualcosa di inaspettato. Un nuovo branch si comporta diversamente dal main, anche se il lockfile dice che tutto dovrebbe coincidere. Se stai già affrontando instabilità nella pipeline, è utile affiancare il debugging della cache a una revisione sistematica del build, come in questa guida su come risolvere i fallimenti di build nelle pipeline CI/CD di Capacitor.
Regola pratica: Considera yarn clear cache come uno strumento di diagnostica, non come un rituale di manutenzione.
La parte complicata è che Yarn ha cambiato il suo modello di cache nel tempo. Nei progetti più vecchi, la cache è condivisa globalmente. Nei progetti più recenti, la pulizia della cache può essere locale al progetto, globale o entrambe, a seconda dei flag del comando. Quindi, quando un collega dice "svuota solo la cache di Yarn", la prima domanda da porsi è: quale Yarn?
Per questo un buon fix della cache parte dal contesto. Macchina locale o CI runner. Yarn v1 o Berry. Cache condivisa o di progetto. Una volta capito questo, il comando diventa preciso invece di essere un tentativo a caso.
Quando e perché svuotare la cache di Yarn
Pulire la cache di Yarn ha senso quando hai in mente un errore specifico. È utile soprattutto per rimuovere artefatti obsoleti dei pacchetti, recuperare da un download corrotto o cancellare deliberatamente i pacchetti salvati per forzare Yarn a ricostruire tutto da zero.
I sintomi che indicano problemi di cache
Alcuni casi sono ideali per svuotare la cache:
- Una dipendenza non si aggiorna: Hai cambiato la versione, o ricostruito un pacchetto locale, ma le installazioni continuano a scaricare un artefatto vecchio.
- Le installazioni falliscono come se dipendessero dallo stato: Una macchina funziona, un'altra no, e rieseguire lo stesso comando produce sempre lo stesso risultato errato.
- Devi recuperare spazio sul disco locale: Questo conta più sulle macchine degli sviluppatori che negli ambienti CI effimeri.
Altre situazioni sembrano solo problemi di cache. Se il lockfile è cambiato inaspettatamente, se la configurazione di un workspace è inconsistente o se un build Docker invalida il layer sbagliato, svuotare la cache non risolverà la causa principale. I team che lavorano ai build delle app si imbattono spesso in questo mentre gestiscono tooling nativo, dipendenze JavaScript e aggiornamenti dei plugin. In questo contesto, questa panoramica pratica su come gestire le dipendenze nei progetti Capacitor conviene tenerlo a portata di mano.
Se l'obiettivo è una pulizia più ampia della macchina piuttosto che il troubleshooting dei pacchetti, può aiutare anche una guida a livello di sistema. Gli sviluppatori Mac che vogliono pulire le cache delle app per utenti Mac spesso scoprono che i package manager sono solo una parte del quadro dello storage.
Quando non usare Yarn clear cache
Non usare Yarn clear cache come prima soluzione a ogni problema di installazione.
Usalo quando ci sono prove di uno stato dei pacchetti obsoleto o corrotto. Saltalo se il problema è più probabilmente:
| Situazione | Mossa migliore |
|---|---|
| Disallineamento del lockfile | Revisione yarn.lock modifiche e reinstallazione coerente |
| Problemi di risoluzione workspace | Controlla la config del workspace e il comportamento di install |
| Lentezza nel rebuild di Docker | Controlla l'ordine dei layer e la persistenza della cache |
| Mismatch in CI | Verifica quali directory vengono effettivamente ripristinate |
Se l'install è errata perché l'ambiente è sbagliato, pulire la cache renderà solo più lenta la prossima install errata.
Questa distinzione fa risparmiare tempo. Molto debugging inutile deriva dal trattare la cache come un tasto reset magico.
Come svuotare la cache in Yarn Classic v1
Yarn Classic si comporta come molti sviluppatori pensano che tutte le versioni di Yarn si comportino. Utilizza una cache globale nella directory dell'utente e yarn cache clean pulisce quella cache condivisa. La documentazione ufficiale di Yarn Classic la descrive così, specificando che la cache viene ripopolata al prossimo yarn o yarn install run secondo il modello della directory utente documentato in nella documentazione CLI della cache di Yarn Classic.
Cosa rimuove effettivamente il comando
Per Yarn v1, il comando di pulizia predefinito è semplice:
yarn cache clean
Quel comando cancella la cache condivisa, non solo il progetto corrente. Se lavori su più repository sulla stessa macchina, questo è importante. Il prossimo install in uno qualsiasi di essi potrebbe dover scaricare nuovamente i pacchetti.
Questo design a cache condivisa è uno dei motivi per cui Yarn v1 può causare comportamenti cross-project confusionari. Un artifact obsoleto nella cache globale può persistere abbastanza a lungo da influenzare diversi repo, specialmente durante lo sviluppo di pacchetti locali.
Una sequenza pratica per Yarn Classic è solitamente questa:
- Esegui prima il comando clean:
yarn cache clean - Remove local install artifacts if needed:
node_modulesè spesso il passo successivo se lo stato appare ancora inconsistente. - Reinstalla da zero: Esegui
yarn installdi nuovo e conferma che il dependency graph si risolva come previsto.
Come verificare la posizione della cache
Quando vuoi ispezionare o rimuovere direttamente la directory della cache, Yarn Classic ti fornisce il percorso:
yarn cache dir
È utile quando il comando CLI non sembra risolvere il problema, o quando devi confermare quale utente possiede la directory della cache in un ambiente condiviso o containerizzato.
Se stai usando una toolchain datata e vuoi mantenere prevedibile il setup locale, questa guida su installare Capacitor CLI passo dopo passo si sposa bene con un reset pulito delle dipendenze.
Un'ispezione manuale della cache è spesso più utile di un secondo comando di pulizia alla cieca.
Per i progetti v1, il modello mentale è semplice. Una cache condivisa, un comando di pulizia globale e il successivo install ripopola ciò che hai rimosso.
Gestione moderna della cache in Yarn Berry v2+
Yarn Berry ha cambiato le regole del gioco. Se sei abituato a Yarn v1, il cambiamento maggiore è che la pulizia della cache non è più solo "cancella lo store globale e riprova". Berry offre un controllo più preciso, utile una volta capito cosa si vuole colpire.
Berry ha cambiato il modello della cache
In Yarn moderno, il comportamento della cache è molto più legato al progetto stesso. Questo si allinea all'approccio di Berry basato sul controllo a livello di progetto, Plug'n'Play e workflow dove le dipendenze possono risiedere accanto al repo invece di un unico modello di cache globale.
Ecco perché i vecchi consigli possono trarre in inganno. Un collega che ha imparato Yarn con la v1 potrebbe aspettarsi un comando per eliminare tutto globalmente. In Berry, devi ragionare in termini di ambito.
Se gestisci diversi output di build tra pipeline mobile e web, lo stesso approccio basato sull'ambito si applica anche fuori dal package management. Questo confronto tra tipi di build è un utile promemoria: le assunzioni sull'ambiente tendono a influenzare il debugging.
Ecco una rapida spiegazione visiva prima dei dettagli sui comandi:
I comandi principali in Berry
La documentazione ufficiale di Yarn yarn cache clean come rimuovere file della cache condivisa, ed espone due switch importanti nella attuale documentazione del comando Yarn cache clean:
yarn cache cleanrimuove i file della cache condivisa di Yarn.yarn cache clean --mirrorpulisce la cache globale invece di quella locale del progetto.yarn cache clean --allrimuove sia i file della cache globale che quelli della cache locale del progetto.
Questo ti permette un workflow più intenzionale rispetto a Yarn v1.
| Obiettivo | Comando |
|---|---|
| Pulisci lo scope di default della cache condivisa | yarn cache clean |
| Punta alla cache del mirror globale | yarn cache clean --mirror |
| Esegui un reset completo dei file di cache locali e globali | yarn cache clean --all |
Usa --all quando vuoi l'equivalente più vicino a “ricominciare da zero”. Usa --mirror quando sai che il problema risiede nel livello della cache globale e non vuoi cancellare tutto il progetto.
Punto di decisione: In Berry, scegliere lo scope sbagliato è uno dei motivi principali per cui una pulizia della cache sembra “non fare nulla”.
Questa è la differenza pratica. Yarn Classic era ampio di default. Berry è esplicito per design.
Best practice per la cache di Yarn in CI/CD e Docker
Nelle pipeline CI/CD, svuotare alla cieca la cache di Yarn è solitamente un errore. Sembra una scelta sicura perché elimina lo stato, ma spesso rimuove proprio ciò di cui la pipeline ha bisogno per velocità e ripetibilità.
La domanda più utile è questa: cosa stai mettendo esattamente in cache e cosa stai ripristinando?
Perché svuotare la cache nelle pipeline è spesso la mossa sbagliata
Una discussione su CircleCI ha evidenziato un pattern di errore comune in molti progetti reali. Gli install rallentati non venivano risolti pulendo la cache, perché il collo di bottiglia non erano gli archivi dei pacchetti obsoleti. Era il comportamento di fetch e link, il mismatch della directory della cache e la mancanza di node_modules percorsi nel set in cache, come descritto in quel Thread di caching Yarn in CircleCI.
Questo è importante perché i sistemi CI spesso nascondono la causa reale dietro un unico sintomo vago: "l'install è lenta" o "lo step delle dipendenze è instabile". Gli sviluppatori allora svuotano la cache, rieseguono tutto e non ottengono alcun miglioramento concreto.
Gli errori comuni nelle pipeline includono:
- Cachare la directory sbagliata: Lo step di restore si completa, ma Yarn non utilizza la posizione ripristinata.
- Ignorare i percorsi del workspace: Le dipendenze root potrebbero essere ripristinate mentre l'installazione del workspace deve ancora essere relinkata.
- Costruire i layer Docker nell'ordine sbagliato: Una copia code della sorgente invalida il layer delle dipendenze, costringendo a reinstallare i pacchetti ogni volta.
In CI, un cache miss causato da una configurazione errata sembra molto simile a una cache corrotta.
Se buildi app mobile in ambienti automatizzati, qui entra in gioco anche il tooling di release. I team spesso combinano GitHub Actions o CircleCI con sistemi di distribuzione e update. Un'opzione in questo workflow più ampio è Configurazione CI/CD di Capgo per app Capacitor, insieme alla tua strategia di package-manager e build-cache.
Un approccio migliore per CI e Docker
Usa l'invalidazione della cache con criterio, non per istinto.
Per la CI, un pattern affidabile è questo:
- Cache basata sullo stato delle dipendenze: Associa le chiavi della cache a
yarn.locke ai file di configurazione Yarn pertinenti. - Ripristina prima dell'installazione: Assicurati che i percorsi ripristinati corrispondano a quelli che Yarn userà in quell'ambiente.
- Installa in modo consistente: In setup immutabili, usa la modalità di installazione che garantisce la correttezza del lockfile.
- Invalida in caso di modifiche reali: Un cambio di versione di Yarn, un aggiornamento del lockfile o del percorso cache è un buon motivo per ricostruire la cache.
Per Docker, i principi sono simili:
- Copia prima i manifest delle dipendenze: Mantieni il layer di installazione delle dipendenze separato dal codice sorgente dell'app, quando possibile.
- Evita pulizie superflue durante la build dell'immagine: Eliminare la cache nello stesso build spesso impedisce il riutilizzo dei layer.
- Sii esplicito sulla proprietà dell'utente: Le directory di cache create da root possono causare errori di installazione per utenti non-root.
Una breve tabella decisionale aiuta:
| Scenario | Azione migliore rispetto a yarn cache clean |
|---|---|
| L'installazione in CI è lenta dopo il restore | Verify cache path and restore order |
| I workspace richiedono ancora molti relink | Cache the relevant workspace install artifacts |
| Il rebuild di Docker riesegue le installazioni | Riordina i layer attorno ai file delle dipendenze |
| Un build errato dopo un cambio di dipendenze | Invalida la cache key, poi rifai un build pulito |
Usa Yarn clear cache in CI solo se hai confermato che il problema sia la cache obsoleta. Spesso, la soluzione è un design migliore della cache.
Risoluzione dei comuni errori della cache di Yarn
Il bug di cache più frustrante è quello che sopravvive a una pulizia. Esegui un cleanup mirato, reinstalli, e Yarn scarica ancora il vecchio pacchetto. A quel punto, viene la tentazione di pensare che il registry sia sbagliato o che il lockfile sia maledetto.
Un problema storico documentato in Yarn spiega perché accade. Gli sviluppatori hanno segnalato che yarn cache clean <package-name> poteva lasciare una vecchia copia in cache/.tmp, il che significava che gli install continuavano a usare la versione obsoleta finché quella directory temporanea non veniva rimossa o non si eseguiva un cleanup completo, come discusso in il problema Yarn relativo agli artefatti di cache obsoleti in .tmp.
Quando un cleanup mirato lascia ancora pacchetti obsoleti
La lezione è semplice. Un cleanup parziale non sempre basta.
Se sospetti un problema di versioni obsolete piuttosto che una corruzione generale, segui questo ordine:
- Inizia dal controllo più ovvio: Conferma di stare debuggando la versione del pacchetto e la sorgente corrette.
- Non fidarti troppo di una pulizia specifica per un pacchetto: Una pulizia mirata potrebbe lasciare dei residui temporanei.
- Passa a una pulizia completa della cache: Se la versione obsoleta persiste, pulisci l'intero scope della cache.
- Inspect temp cache paths manually: In configurazioni più vecchie,
cache/.tmppotrebbe essere l'anello mancante.
Quando un pacchetto continua a risolversi su un vecchio artifact, i file della cache temporanea sono spesso il primo posto che controllerei dopo una pulizia mirata fallita.
Problemi di permessi o di ambiente che sembrano problemi di cache
Non tutti gli "errori di cache" riguardano il contenuto della cache.
In Docker, in sistemi Linux multi-utente o nei runner CI, potresti riscontrare errori di permessi perché la directory della cache è di proprietà di un utente diverso dal processo che esegue Yarn. In questo caso, svuotare la cache non servirà finché non si risolve il problema di ownership. La soluzione pratica è eseguire Yarn con l'utente corretto o ripristinare i permessi della directory prima di reinstallare.
Problemi del genere si presentano spesso come cache obsoleta, poiché le installazioni falliscono in modo inconsistente tra i vari ambienti. La soluzione è operativa, non legata al pacchetto.
Domande frequenti sulla pulizia della cache di Yarn
È sicuro svuotare la cache di Yarn?
Sì. In uno scenario di sviluppo normale è un'operazione sicura perché stai rimuovendo gli artefatti dei pacchetti in cache, non eliminando il codice sorgente della tua applicazione. Yarn scaricherà nuovamente ciò di cui ha bisogno al prossimo install.
Il compromesso è il tempo. Una cache pulita significa che la prossima installazione potrebbe richiedere più download o rebuild del solito.
Quanto spesso va fatto?
Solo quando c'è un motivo valido.
L'operazione di pulizia della cache di Yarn non dovrebbe essere una manutenzione di routine su un progetto sano. Se la inserisci in ogni workflow per abitudine, rallenterai le installazioni locali e comprometterai il caching della CI. Usala quando le dipendenze sono obsolete, le installazioni sembrano corrotte o hai bisogno di un reset deliberato durante il debugging.
Affecterà le build in produzione?
Non direttamente. Svuotare la cache locale o della CI non modifica il code dell'applicazione che hai committato.
Quello che cambia è l'ambiente che prepara la build. Se la tua pipeline di produzione dipende da artefatti di installazione in cache, svuotarli può rallentare le build o far emergere problemi di riproducibilità nascosti. È utile in fase di troubleshooting, ma non è qualcosa da infilare negli script di release senza un motivo.
Qual è la regola pratica più semplice da seguire?
Usa la pulizia minima necessaria per risolvere il problema.
Per il debugging locale, parti dallo scope della cache che Yarn usa in quel progetto. Per CI e Docker, correggi il design della cache prima di iniziare a svuotare le cache. E se la pulizia specifica per pacchetto non funziona, ipotizza artefatti temporanei o un mismatch dell'ambiente prima di pensare che Yarn sia rotto.
Se il tuo team rilascia app Capacitor e ha bisogno di una pipeline di rilascio più pulita dopo problemi di build o dipendenze, Capgo è un'opzione per distribuire aggiornamenti di JavaScript e asset senza attendere la revisione degli store, mantenendo il processo di build e rollout separato dal troubleshooting della cache dei pacchetti.
