Vous lancez yarn install, et la dépendance que vous venez de mettre à jour pointe toujours vers l'ancien build. Ou votre ordinateur installe tout correctement alors que la CI échoue soudainement après un changement anodin du lockfile. Ou encore, les rebuilds Docker s'éternisent, même si vous « utilisez le cache ».
C'est généralement à ce moment-là que l'on cherche Yarn clear cache pour copier-coller la première commande trouvée.
Parfois, cela fonctionne. Parfois, cela ne change rien. La raison est simple : le comportement du cache de Yarn dépend fortement de la version de Yarn que vous utilisez, et de la différence entre Yarn Classic v1 et Yarn Berry v2+ est assez importante pour changer à la fois la bonne commande et la bonne stratégie de dépannage.
La plupart des guides s'arrêtent à yarn cache clean. Ce n'est que le début. Ce qui compte, c'est la portée du cache, si votre projet utilise un cache local ou partagé, et si votre problème vient réellement du cache. En CI et Docker, une mauvaise stratégie de cache cause souvent plus de soucis que des archives de packages obsolètes.
Table of Contents
- Votre build est cassé et le cache Yarn est peut-être le coupable
- Quand et pourquoi vider votre cache Yarn
- Vider le cache dans Yarn Classic v1
- La gestion moderne du cache dans Yarn Berry v2+
- Bonnes pratiques du cache Yarn pour CI/CD et Docker
- Dépannage des erreurs de cache Yarn courantes
- Foire aux questions sur le nettoyage du cache Yarn
Votre build est cassé et le cache Yarn est peut-être le coupable
Ce schéma vous est familier : vous mettez à jour un package, vous récupérez les derniers changements et vous relancez l'install. La commande se termine, mais l'app se comporte toujours comme si l'ancienne dépendance était encore là. Quelqu'un suggère alors de vider le cache, et vous vous demandez si c'est une vraie solution ou une simple superstition.
Cela peut être une vraie solution. Cela peut aussi être une distraction.
Les problèmes de cache se manifestent généralement de quelques manières prévisibles. Un package local ne s'actualise pas. La CI récupère quelque chose d'inattendu. Une nouvelle branche se comporte différemment de la branche principale alors que le lockfile indique que tout devrait correspondre. Si vous traitez déjà une instabilité plus large de votre pipeline, il est utile de coupler le débogage du cache avec une revue de build plus systématique, comme dans ce guide sur résoudre les échecs de build dans les pipelines CI/CD de Capacitor.
Règle pratique : Considérez Yarn clear cache comme un outil de diagnostic, pas comme un rituel de maintenance.
La difficulté réside dans le fait que Yarn a fait évoluer son modèle de cache au fil du temps. Dans les anciens projets, le cache est partagé globalement. Dans les projets plus récents, le nettoyage du cache peut être local au projet, global, ou les deux, selon les flags de la commande. Ainsi, quand un collègue dit « vide juste le cache Yarn », la première question à poser est : Quel Yarn ?
C'est pourquoi une bonne correction du cache commence par le contexte. Machine locale ou runner CI. Yarn v1 ou Berry. Cache partagé ou cache de projet. Une fois que vous savez cela, la commande devient précise au lieu de reposer sur la chance.
Quand et pourquoi vider votre cache Yarn
Vider le cache Yarn est pertinent lorsque vous faites face à un mode d'échec spécifique. C'est particulièrement utile pour supprimer des artefacts de packages obsolètes, récupérer d'un état de téléchargement corrompu ou effacer délibérément les packages stockés pour que Yarn reconstruise tout de zéro.
Les symptômes qui indiquent un problème de cache
Certains cas nécessitent un nettoyage du cache :
- Une dépendance refuse de se mettre à jour : Vous avez changé la version, ou reconstruit un package local, mais les installations récupèrent toujours un artefact plus ancien.
- Les installations échouent de manière persistante : Une machine fonctionne, une autre non, et relancer la même commande produit systématiquement le même mauvais résultat.
- Vous devez récupérer de l'espace disque local : Cela importe plus sur les machines de développement que dans les environnements CI éphémères.
D'autres situations ressemblent simplement à des problèmes de cache. Si votre lockfile a changé de manière inattendue, si la configuration d'un workspace est incohérente, ou si un build Docker invalide la mauvaise couche, vider le cache ne réglera pas la cause profonde. Les équipes travaillant sur des builds d'applications rencontrent souvent cela en jonglant entre les outils natifs, les dépendances JavaScript et les mises à jour de plugins. Dans ce contexte, ce guide pratique sur la gestion des dépendances dans les projets Capacitor mérite d'être conservé sous la main.
Si votre objectif est un nettoyage plus large de la machine plutôt que le dépannage de packages, un guide au niveau système peut aussi aider. Les développeurs Mac qui souhaitent nettoyer les caches d'applications pour les utilisateurs Mac découvrent souvent que les gestionnaires de packages ne sont qu'une partie du stockage.
Quand ne pas utiliser Yarn clear cache
N'utilisez pas Yarn clear cache comme première réponse à chaque problème d'installation.
Utilisez-le lorsqu'il y a des preuves d'un état de package obsolète ou corrompu. Ignorez-le si le problème est plus probablement lié à :
| Situation | Meilleure première étape |
|---|---|
| Dérive du lockfile | Examinez yarn.lock les changements et réinstallez de manière cohérente |
| Problèmes de résolution de workspace | Check workspace config and install behavior |
| Lenteur du rebuild Docker | Examinez l'ordre des layers et la persistance du cache |
| Incohérence CI | Vérifiez quels répertoires sont réellement restaurés |
Si l'installation échoue à cause d'un environnement incorrect, vider le cache ne fera que ralentir la prochaine installation erronée.
Cette distinction fait gagner du temps. Beaucoup de débogage inutile provient du fait de traiter le cache comme un bouton de réinitialisation magique.
Vider le cache dans Yarn Classic v1
Yarn Classic se comporte comme beaucoup de développeurs imaginent encore que toutes les versions de Yarn fonctionnent. Il utilise un cache global dans le répertoire utilisateur, et yarn cache clean efface ce cache partagé. La documentation de Yarn Classic le décrit elle-même ainsi, et précise que le cache est repeuplé à la prochaine yarn ou yarn install exécution selon le modèle de répertoire utilisateur documenté dans la doc du cache Yarn Classic CLI.
Ce que la commande supprime vraiment
Pour Yarn v1, la commande de nettoyage par défaut est simple :
yarn cache clean
Cette commande efface le cache partagé, pas seulement le projet actuel. Si vous travaillez sur plusieurs dépôts sur la même machine, ça compte. La prochaine installation dans l'un d'eux devra peut-être récupérer les packages à nouveau.
Cette architecture de cache partagé explique en partie pourquoi Yarn v1 peut générer des comportements déroutants d'un projet à l'autre. Un artefact obsolète dans le cache global peut survivre assez longtemps pour affecter d'autres repos, surtout quand on développe des packages en local.
Une séquence pratique pour Yarn Classic ressemble généralement à ceci :
- Exécutez d'abord la commande clean :
yarn cache clean - Supprimez les artefacts d'installation locaux si nécessaire :
node_modulesest souvent la prochaine étape si l'état semble toujours incohérent. - Réinstallez tout de zéro : Exécutez
yarn installà nouveau et confirmez que le graphe de dépendances se résout comme prévu.
Comment vérifier l'emplacement du cache
Lorsque vous souhaitez inspecter ou supprimer directement le répertoire de cache, Yarn Classic vous donne le chemin :
yarn cache dir
C'est utile quand la commande CLI ne semble pas résoudre le problème, ou quand vous devez confirmer quel compte utilisateur possède le répertoire de cache dans un environnement partagé ou conteneurisé.
Si vous travaillez avec une ancienne toolchain et que vous essayez de garder votre configuration locale prévisible, ce guide sur l'installation de Capacitor CLI étape par étape pairs well with a clean dependency reset.
Une inspection manuelle du cache est souvent plus utile qu'une seconde commande de nettoyage à l'aveugle.
Pour les projets en v1, le modèl’est simple. Un cache partagé, une commande de nettoyage globale, et la prochaine installation réinstalle ce que vous avez supprimé.
La gestion moderne du cache dans Yarn Berry v2+
Yarn Berry a changé la donne. Si vous avez l'habitude de Yarn v1, le plus gros changement est que le nettoyage du cache ne consiste plus seulement à « effacer le store global et réessayer ». Berry permet un contrôle plus précis, ce qui est utile une fois que vous savez ce que vous ciblez.
Berry a changé le modèle de cache
Avec le Yarn moderne, le comportement du cache est beaucoup plus étroitement lié au projet lui-même. Cela correspond à l'approche plus large de Berry autour du contrôl’au niveau du projet, du Plug’n’Play et des workflows où les dépendances peuvent coexister avec le repo plutôt que dans un modèle de cache unique pour toute la machine.
C'est pourquoi les vieux conseils peuvent vous induire en erreur. Un collègue ayant appris Yarn sur la v1 peut s'attendre à ce qu'une seule commande purge tout globalement. Avec Berry, vous devez raisonner en termes de scope.
Si vous faites face à des builds différents entre vos pipelines mobile et web, cette même approche s'applique également en dehors de la gestion des packages. Cette comparaison de types de builds est un rappel utile que les suppositions sur l'environnement ont tendance à fausser le débogage.
Voici une explication visuelle rapide avant les détails de la commande :
Les commandes qui comptent dans Berry
La documentation de Yarn moderne yarn cache clean en supprimant fichiers de cache partagés, et elle expose deux options importantes dans la référence actuelle de la commande Yarn cache clean:
yarn cache cleansupprime les fichiers de cache partagés de Yarn.yarn cache clean --mirrorvide le cache global au lieu du cache local du projet.yarn cache clean --allsupprime à la fois les fichiers du cache global et ceux du cache local du projet actuel.
Cela vous offre un workflow plus intentionnel que Yarn v1.
| Objectif | Commande |
|---|---|
| Nettoyer le scope du cache partagé par défaut | yarn cache clean |
| Cibler le cache mirror global | yarn cache clean --mirror |
| Do a full reset across local and global cache files | yarn cache clean --all |
Utilisez --all quand vous voulez l'équivalent le plus proche de « repartir de zéro ». Utilisez --mirror quand vous savez que le problème vient de la couche de cache global et que vous ne voulez pas tout supprimer dans le projet.
Point de décision : Avec Berry, choisir le mauvais scope est l'une des raisons principales pour lesquelles un nettoyage de cache semble « ne rien faire ».
C'est là que réside la différence pratique. Yarn Classic était large par défaut. Berry est explicite par conception.
Bonnes pratiques du cache Yarn pour CI/CD et Docker
En CI/CD, vider aveuglément le cache Yarn est généralement une erreur. Cela semble sûr car cela supprime l'état, mais cela supprime souvent l'état même dont votre pipeline a besoin pour sa rapidité et sa répétabilité.
La question la plus pertinente est la suivante : que mettez-vous exactement en cache, et que restaurez-vous précisément ?
Pourquoi vider le cache dans les pipelines est souvent une mauvaise idée
A CircleCI discussion captured a failure pattern many teams hit in real projects. Slow installs weren’t fixed by cache cleanup because the bottleneck wasn’t stale package archives. It was fetch and link behavior, cache-directory mismatch, and missing node_modules chemins dans l'ensemble mis en cache, comme décrit dans ce Fil de cache Yarn sur CircleCI.
C'est important car les systèmes de CI cachent souvent la cause sous-jacente derrière un symptôme vague : « l'installation est lente » ou « l'étape des dépendances est instable ». Les développeurs vident alors le cache, relancent, et n'obtiennent aucune amélioration significative.
Les erreurs courantes de pipeline incluent :
- Mettre en cache le mauvais répertoire : L'étape de restauration se termine, mais Yarn n'utilise pas l'emplacement restauré.
- Ignorer les chemins de workspace : Les dépendances racine peuvent être restaurées alors que le relienage du workspace est encore en cours.
- Construire les couches Docker dans le mauvais ordre : Une copie source code invalide la couche de dépendances, ce qui relance l'installation des packages à chaque fois.
En CI, un cache miss dû à une mauvaise configuration ressemble beaucoup à un cache corrompu.
Si vous compilez des apps mobiles dans des environnements automatisés, c'est aussi là que les outils de release interviennent. Les équipes combinent souvent GitHub Actions ou CircleCI avec des systèmes de distribution et de mise à jour. Une option dans ce workflow plus large est la configuration CI/CD de Capgo pour les apps Capacitor, parallèlement à votre stratégie de gestionnaire de paquets et de cache de build.
Une meilleure approche pour la CI et Docker
Utilisez l'invalidation de cache de manière délibérée, pas émotionnelle.
Pour la CI, un pattern fiable ressemble à ceci :
- Cache basé sur l'état des dépendances : Liez les clés de cache à
yarn.locket aux fichiers de config Yarn pertinents. - Restaurer avant l'install : Assurez-vous que les chemins restaurés correspondent à ceux que Yarn utilisera dans cet environnement.
- Installer de manière cohérente : Dans les environnements immuables, utilisez le mode d'install qui impose la validité du lockfile.
- Invalider lors de changements réels : Un changement de version Yarn, une mise à jour du lockfile ou du chemin de cache justifie de reconstruire le cache.
Pour Docker, les principes sont similaires :
- Copier les manifestes de dépendances d'abord : Séparez la couche d'installation des dépendances du code source de l'application quand c'est possible.
- Évitez le nettoyage inutile lors du build de l'image : Supprimer le cache au sein d'un même build élimine souvent la réutilisation utile des layers.
- Soyez explicite sur la propriété utilisateur : Les répertoires de cache créés par root peuvent provoquer des échecs d'installation ultérieurs pour un utilisateur runtime non-root.
Un tableau de décision rapide aide :
| Scénario | Meilleure action que yarn cache clean |
|---|---|
| L'installation CI est lente après le restore | Vérifier le chemin du cache et l'ordre de restore |
| Les workspaces nécessitent encore beaucoup de relink | Mettre en cache les artefacts d'installation des workspaces concernés |
| Le rebuild Docker relance les installs | Réorganiser les layers autour des fichiers de dépendances |
| Un build cassé après un changement de dépendance | Invalidez la clé de cache, puis relancez un build propre |
N'utilisez Yarn clear cache en CI que si vous avez confirmé que le contenu obsolète du cache est bien le problème. La plupart du temps, la solution réside dans une meilleure conception du cache.
Dépannage des erreurs de cache Yarn courantes
Le bug de cache le plus frustrant est celui qui survit à un nettoyage. Vous lancez un nettoyage ciblé, vous réinstallez, et Yarn récupère toujours l'ancien package. À ce stade, on est tenté de croire que le registry est en cause ou que le lockfile est hanté.
Un problème historique documenté dans Yarn explique pourquoi cela arrive. Des développeurs ont rapporté que yarn cache clean <package-name> pouvait laisser une ancienne copie dans cache/.tmp, ce qui voulait dire que les installations continuaient d'utiliser la version obsolète jusqu'à la suppression de ce répertoire temporaire ou un nettoyage complet, comme évoqué dans le ticket Yarn sur les artefacts de cache obsolètes dans .tmp.
Quand un nettoyage ciblé laisse encore traîner des packages obsolètes
La leçon est simple. Un nettoyage partiel ne suffit pas toujours.
Si vous suspectez une version obsolète plutôt qu'une corruption généralisée, suivez cet ordre :
- Commencez par la vérification évidente : Confirmez que vous débuggez la version du package et la source attendues.
- Ne faites pas trop confiance à un nettoyage ciblé par package : Un nettoyage ciblé peut laisser des artefacts temporaires.
- Passez à un nettoyage complet du cache : Si la version obsolète persiste, nettoyez le cache à une échelle plus large.
- Inspect temp cache paths manually: Dans les configurations plus anciennes,
cache/.tmppeut être l'élément manquant.
Lorsqu'un package continue de pointer vers un ancien artefact, les fichiers de cache temporaires sont souvent le premier endroit que j'inspecte après l'échec d'un nettoyage ciblé.
Problèmes de permissions et d'environnement qui ressemblent à des soucis de cache
Toutes les « erreurs de cache » ne sont pas liées au contenu du cache.
Dans Docker, les systèmes Linux multi-utilisateurs ou les runners CI, vous pouvez rencontrer des échecs de permission car le répertoire de cache appartient à un utilisateur différent du processus qui exécute Yarn. Dans ce cas, vider le cache ne servira à rien tant que le problème de propriété n'est pas résolu. La solution pratique consiste à exécuter Yarn avec le bon utilisateur ou à réparer la propriété du répertoire avant de réinstaller.
Ce type de problème ressemble souvent à un cache obsolète car les installations échouent de manière incohérente selon les environnements. La correction est opérationnelle, pas liée au package.
Foire aux questions sur le nettoyage du cache Yarn
Est-il sûr de vider le cache Yarn ?
Oui. En développement classique, c'est une opération sûre car vous supprimez des artefacts de packages mis en cache, et non le code source de votre application. Yarn pourra récupérer ce dont il a besoin lors de la prochaine installation.
Le compromis est le temps. Un cache vide signifie que la prochaine installation pourrait nécessiter plus de téléchargements ou de rebuilds que d'habitude.
À quelle fréquence faut-il le faire ?
Seulement si vous avez une raison précise.
Le `yarn cache clean` ne devrait pas être une maintenance de routine sur un projet sain. Si vous l'intégrez par habitude dans chaque workflow, vous ralentirez les installations locales et compromettrez le caching de la CI. Utilisez-le lorsque les dépendances sont obsolètes, que les installations semblent corrompues ou que vous avez besoin d'une réinitialisation délibérée lors du débogage.
Cela affectera-t-il les builds de production ?
Pas directement. Vider votre cache local ou CI ne modifie pas le code de l'application que vous avez commit.
Ce qui change, c'est l'environnement qui prépare le build. Si votre pipeline de production dépend d'artefacts d'installation mis en cache, les supprimer peut ralentir les builds ou révéler des problèmes de reproductibilité cachés. C'est utile pour le dépannage, mais ce n'est pas une pratique à intégrer dans vos scripts de release sans raison précise.
Quelle est la règle pratique la plus simple à suivre ?
Utilisez le nettoyage le plus ciblé possible selon le problème.
Pour le débogage local, commencez par le scope de cache utilisé par Yarn dans ce projet. Pour la CI et Docker, corrigez la conception du cache avant de commencer à tout supprimer. Et quand un nettoyage spécifique à un package ne fonctionne pas, suspectez des artefacts temporaires ou un décalage d'environnement avant de conclure que Yarn est défaillant.
Si votre équipe déploie des apps Capacitor et a besoin d'un pipeline de release plus propre après des problèmes de dépendances ou de build, Capgo est une option pour livrer des mises à jour de JavaScript et d'assets sans attendre la validation des stores, tout en gardant votre processus de build et de rollout séparé du dépannage du cache des packages.
