Vous exécutez yarn install, et la dépendance que vous venez de mettre à jour se résout toujours à la version de build ancienne. Ou votre ordinateur installe bien tout en temps, tandis que CI échoue soudainement après une modification sans danger de fichier de verrouillage. Ou Docker rebat les cartes, même si vous êtes « en train d'utiliser la cache ».
C'est généralement à ce moment-là que les gens cherchent à Yarn clear cache et collent la première commande qu'ils trouvent.
Parfois, cela fonctionne. Parfois, cela ne résout rien. La raison est simple : le comportement de la cache de Yarn dépend fortement de la version de Yarn que vous utilisez, et la différence entre Yarn Classic v1 et Yarn Berry v2+ est suffisamment grande pour changer à la fois la bonne commande et la bonne stratégie de dépannage.
La plupart des guides s'arrêtent à yarn cache cleanC'est là que commence vraiment l'aventure. Ce qui compte, c'est la portée de la cache, si votre projet utilise une cache locale ou partagée, et si votre problème réel n'est même pas la cache.
Table des matières
- Votre build est cassé et Yarn Cache pourrait en être la cause
- Quand et pourquoi vider votre cache Yarn
- Vider le cache dans Yarn Classic v1
- Gestion du cache moderne dans Yarn Berry v2+
- Meilleures pratiques de cache Yarn pour CI/CD et Docker
- Résolution des erreurs courantes de cache Yarn
- Questions fréquentes sur la suppression du cache Yarn
Votre build est cassé et le cache Yarn pourrait en être la cause
Un modèle familier ressemble à ceci. Vous augmentez une package, vous récupérez des changements frais, et vous exécutez install à nouveau. La commande est terminée, mais l'application se comporte toujours comme si la dépendance ancienne était présente. Ensuite, quelqu'un suggère de vider le cache, et maintenant vous vous demandez si c'est une vraie solution ou juste une superstition.
Cela peut être une vraie solution. Cela peut également être une distraction.
Les problèmes de cache se manifestent généralement de quelques façons prévisibles. Un package local ne se met pas à jour. CI récupère quelque chose inattendu. Une branche fraîche se comporte différemment de la branche principale même si le fichier de verrouillage dit que tout devrait correspondre. Si vous poursuivez déjà des instabilités plus larges de pipeline, il est utile de pairer la débogage du cache avec une revue de build plus systématique, comme ce guide sur fixing build failures in Capacitor pipelines de CI/CD.
Practical rule: Traitez la purge de cache Yarn comme un outil de diagnostic, et non comme un rituel de maintenance.
La partie difficile est que Yarn a changé son modèle de cache au fil du temps. Dans les anciens projets, le cache est partagé globalement. Dans les projets plus récents, la purge du cache peut être locale au projet, globale ou les deux, en fonction des drapeaux de commande. Alors que lorsque l'un de vos collègues dit « purgez simplement le cache Yarn », la première question devrait être : lequel Yarn ?
C'est pourquoi une bonne solution de cache commence par le contexte. Ordinateur local ou exécuteur de CI. Yarn v1 ou Berry. Cache partagé ou cache du projet. Une fois que vous savez cela, la commande devient précise au lieu d'être pleine d'espoir.
Quand et pourquoi vider le cache Yarn
Vider le cache Yarn a du sens lorsque vous avez un mode de panne spécifique en tête. C'est le plus utile lorsque vous avez besoin de supprimer les artefacts de packages obsolètes, de récupérer un état de téléchargement brisé ou de faire volontairement disparaître les packages stockés afin que Yarn les reconstitue à partir de zéro.
Les symptômes qui indiquent des problèmes de cache
Certains cas sont des candidats de cache solides :
- Un dépendance refuse de se mettre à jour : You avez modifié la version, ou reconstruit un package local, mais les installations tirent toujours un artefact plus ancien.
- Les installations échouent de manière qui ressemble à un état : Une machine fonctionne, une autre ne fonctionne pas, et la reprise du même commandement reproduit toujours le même mauvais résultat.
- Vous devez récupérer de l'espace disque local : Cela compte plus sur les machines de développement que dans les environnements CI de courte durée.
D'autres situations ne ressemblent qu'à des problèmes de cache. Si votre fichier de verrouillage a changé inattendement, si une configuration de bureau est incohérente, ou si une construction Docker invalide la mauvaise couche, la suppression du cache ne résoudra pas la cause racine. Les équipes travaillant sur les builds d'applications rencontrent souvent cela en jonglant avec les outils natifs, les dépendances JavaScript et les mises à jour de plugins. Dans ce contexte, cet aperçu pratique de la gestion des dépendances dans les projets __CAPGO_KEEP_0__ est utile de garder à portée de main. managing dependencies in Capacitor projects Quand ne pas chercher à Yarn clear cache
Quand ne pas chercher à Yarn clear cache Quand ne pas chercher à Yarn clear cache Quand ne pas chercher à Yarn clear cache
Quand ne pas chercher à Yarn clear cache
N'employez pas la purge de Yarn comme réponse initiale à chaque problème d'installation.
Utilisez-le lorsque vous avez des preuves d'état de package périmé ou corrompu.
| Situation | Premier mouvement à privilégier |
|---|---|
| Décalage de fichier de contrôle | Révisez et réinstallez de manière cohérente yarn.lock Problèmes de résolution de l'arborescence de travail |
| Vérifiez la configuration de l'arborescence de travail et le comportement d'installation | Lenteur de la reconstruction de Docker |
| Révisez l'ordre des couches et la persistance de la cache | Mauvaise correspondance CI |
| __CAPGO_KEEP_0__ | Vérifiez lesquels des répertoires sont effectivement restaurés |
Si l'installation est fausse en raison d'un environnement incorrect, la suppression du cache ne fait que rendre la prochaine installation fausse plus lente.
Cette distinction économise du temps. Une grande partie de la débogage gaspillé provient du traitement du cache comme d'un bouton de réinitialisation magique.
Supprimer le Cache dans Yarn Classic v1
Yarn Classic se comporte comme le font encore de nombreux développeurs qui supposent que toutes les versions de Yarn se comportent de la même manière. Il utilise un cache global dans le répertoire utilisateur, et yarn cache clean efface ce cache partagé. La documentation de Yarn Classic la décrit ainsi, et note que le cache est repopulé lors de la prochaine yarn ou yarn install exécution dans le modèle de répertoire utilisateur documenté dans les documents de cache de Yarn Classic CLI.
Ce que la commande supprime réellement
Pour Yarn v1, la commande de nettoyage par défaut est claire :
yarn cache clean
Cette commande efface la cache partagé, et non seulement le projet actuel. Si vous travaillez sur plusieurs dépôts sur la même machine, cela compte. La prochaine installation dans l'un d'eux peut devoir récupérer à nouveau les packages.
Cette conception de cache partagé est l'une des raisons pour lesquelles Yarn v1 peut produire un comportement transversal entre projets confus. Un artefact périmé dans le cache global peut survivre longtemps pour affecter différents dépôts, surtout lorsqu'il s'agit de développement de packages locaux.
Une séquence pratique pour Yarn Classic ressemble généralement à ceci :
- Exécutez la commande de nettoyage en premier :
yarn cache clean - Supprimez les artefacts d'installation locale si nécessaire :
node_modulesest souvent le prochain candidat lorsque l'état semble toujours incohérent. - Réinstallez à partir de zéro : Exécutez
yarn installà nouveau et confirmez que le graphique de dépendances se résout comme prévu.
Comment vérifier l'emplacement du cache
Lorsque vous souhaitez inspecter ou supprimer le répertoire de cache directement, Yarn Classic vous donne le chemin :
yarn cache dir
Cela est utile lorsque le commandement CLI ne semble pas résoudre le problème, ou lorsque vous avez besoin de confirmer quel compte utilisateur possède le répertoire de cache dans un environnement partagé ou conteneurisé.
Si vous travaillez dans un outilchain plus ancien et que vous essayez de garder la configuration locale prévisible, ce guide sur l'installation de Capacitor CLI étape par étape se marie bien avec une réinitialisation des dépendances propre.
Une inspection de cache manuelle est souvent plus précieuse qu'une deuxième commande de nettoyage aveugle.
Pour les projets v1, le modèle mental est simple. Un cache partagé unique, une commande de nettoyage large et la prochaine installation repopule ce que vous avez supprimé.
Gestion de Cache Moderne dans Yarn Berry v2+
Yarn Berry a changé la conversation. Si vous êtes habitué à Yarn v1, la plus grande adaptation est que la suppression du cache n'est plus juste « effacer la zone de stockage globale et essayer à nouveau ». Berry offre un contrôle plus précis, qui est utile une fois que vous savez ce que vous ciblez.
Berry a changé le modèle de cache
Dans Yarn moderne, le comportement du cache est lié beaucoup plus étroitement au projet lui-même. Cela correspond à l'approche plus large de Berry autour du contrôle au niveau du projet, Plug’n’Play et des workflows où les dépendances peuvent vivre aux côtés du dépôt plutôt qu'en un seul modèle de cache machine-à-machines.
C'est pourquoi les conseils anciens peuvent vous tromper. Un collègue qui a appris Yarn sur v1 peut s'attendre à une seule commande pour purger tout globalement. Dans Berry, vous devez penser en termes de __CAPGO_KEEP_0__.
Si vous vous occupez de différents résultats de build sur les pipelines mobile et web, le même esprit de portée s'applique également en dehors de la gestion de packages. Cette comparaison des __CAPGO_KEEP_0__ est un rappel utile que les hypothèses d'environnement tendent à se filtrer dans la débogage.
Voici une explication visuelle rapide avant les détails des commandes :
Les commandes qui comptent dans Berry
Les documents Yarn modernes yarn cache clean en supprimant les fichiers de cache partagés, et il expose deux commutateurs importants dans la référence actuelle des commandes de nettoyage du cache Yarn:
yarn cache cleansupprime les fichiers de cache partagé de Yarn.yarn cache clean --mirrorefface le cache global au lieu du cache local du projet.yarn cache clean --allsupprime les fichiers de cache global et les fichiers de cache local du projet actuel.
Cela vous donne un flux de travail plus intentionnel que Yarn v1.
| Objectif | Commande |
|---|---|
| Nettoyez l'étendue de cache partagé par défaut | yarn cache clean |
| Ciblez le cache miroir global | yarn cache clean --mirror |
| Effectuez un réglage complet sur les fichiers de cache local et global | yarn cache clean --all |
Utilisez --all lorsque vous voulez l'équivalent le plus proche de « commencer complètement à zéro ». Utilisez --mirror lorsque vous savez que le problème se situe dans la couche de cache global et que vous ne voulez pas effacer tout dans le projet.
Point de décision : Dans la région de Berry, choisir le mauvais périmètre est l'une des principales raisons pour lesquelles une purge de cache semble « ne rien faire ».
C'est la différence pratique. Yarn Classic était large par défaut. Berry est explicite par conception.
Pratiques de cache Yarn pour les CI/CD et Docker
Dans les CI/CD, effacer le cache Yarn sans réfléchir est généralement une erreur. Cela ressemble à une sécurité car il supprime l'état, mais il supprime souvent l'état même sur lequel votre pipeline dépend pour la vitesse et la répétabilité.
La question plus utile est celle-ci : Qu'est-ce que vous cachez exactement, et qu'est-ce que vous restaurez exactement ?
Pourquoi la suppression du cache dans les pipelines est souvent une erreur
Un discussion de CircleCI a capturé un modèle de défaillance que de nombreux équipes rencontrent dans des projets réels. Les installations lentes n'étaient pas résolues par la purge de cache car le bouchon n'était pas les archives de packages obsolètes. C'était le comportement de récupération et de liaison, la désynchronisation du répertoire de cache, et les chemins manquants dans l'ensemble de cache, comme décrit dans ce node_modules thread de caching Yarn de CircleCI Le thread de discussion de CircleCI sur le caching Yarn.
That matters because CI systems often hide the underlying cause behind one vague symptom: “l'installation est lente” ou “l'étape de dépendance est instable.” Les développeurs réessayent ensuite, en vidant le cache, et n'obtiennent pas d'amélioration significative.
Les erreurs courantes des pipelines incluent :
- Cachez le mauvais répertoire : L'étape de restauration est terminée, mais Yarn ne utilise pas la localisation restaurée.
- Ignorez les chemins de travail : Les dépendances de base peuvent être restaurées tandis que l'installation de travail doit encore être reliaisonnée.
- Construire les couches Docker dans l'ordre incorrect : Une copie source code invalide la couche de dépendance, donc l'installation de package se réexécute chaque fois.
Dans CI, un manque de cache causé par une mauvaise configuration ressemble beaucoup à un cache corrompu.
Si vous construisez des applications mobiles dans des environnements automatisés, c'est également là où les outils de publication entrent en scène. Les équipes combinent souvent des GitHub Actions ou CircleCI avec des systèmes de distribution et de mise à jour. Une option dans ce flux de travail plus large est Capgo's CI/CD setup pour les applications Capacitor, en parallèle de votre stratégie de package-manager et de cache de build.
Une meilleure approche CI et Docker
Utilisez l'invalidation de cache avec intention, et non avec émotion.
Pour CI, un modèle fiable ressemble à ceci :
- Cachez en fonction de l'état de dépendance : Reliez les clés de cache à
yarn.locket les fichiers de configuration Yarn pertinents. - Restaurez avant l'installation : Assurez-vous que les chemins restaurés correspondent aux chemins que Yarn utilisera dans cet environnement.
- Installez de manière cohérente : Dans les configurations immuables, utilisez le mode d'installation qui impose la correction du fichier de verrou.
- Invalidez en cas de changements réels : Un changement de version de Yarn, une mise à jour du fichier de verrou ou un changement de chemin de cache est un bon motif pour reconstruire le cache.
Pour Docker, les principes sont similaires :
- Copiez d'abord les manifestes de dépendances : Conservez la couche d'installation de dépendances séparée de la source d'application lorsque possible.
- Évitez les nettoyages inutiles lors de la construction de l'image : La suppression du cache à l'intérieur de la même construction supprime souvent l'utilisation utile des couches.
- Soyez explicite sur la propriété de l'utilisateur : Les répertoires de cache créés par root peuvent créer des erreurs d'installation ultérieures pour un utilisateur runtime non-root.
Une petite table de décision aide :
| Scénario | Mieux vaut l'action que yarn cache clean |
|---|---|
| L'installation de CI est lente après restauration | Vérifiez l'ordre de restauration et le chemin de cache |
| Les espaces de travail se reliaient encore lourdement | Cachez les artefacts d'installation pertinents du workspace |
| Rebâtissez Docker pour relancer les installations | Réorganisez les couches autour des fichiers de dépendances |
| Une mauvaise construction après changement de dépendance | Annulez la clé de cache, puis rebâtissez proprement |
Utilisez Yarn clear cache en CI uniquement lorsque vous avez confirmé que le contenu de cache obsolète est le véritable problème. La plupart du temps, la solution est une meilleure conception de cache.
Résoudre les erreurs courantes de cache Yarn
Le bug de cache le plus frustrant est celui qui survit à une purge de cache. Vous exécutez une purge ciblée, réinstallez et Yarn tire toujours l'ancienne package. À ce stade, il est tentant de supposer que le registre est incorrect ou que le fichier de verrouillage est hanté.
Un problème historique documenté dans Yarn montre pourquoi cela se produit. Les développeurs ont signalé que yarn cache clean <package-name> pouvait laisser une copie ancienne derrière dans cache/.tmp, ce qui signifiait que les installations continuaient à utiliser la version obsolète jusqu'à ce que le répertoire temporaire soit supprimé ou une purge complète soit effectuée, comme discuté dans le problème Yarn concernant les artefacts de cache obsolètes dans .tmp.
Lorsqu'une purge ciblée laisse encore des paquets obsolètes derrière elle
La leçon est simple. Une purge partielle n'est pas toujours suffisante.
Si vous suspectez une staleness de version plutôt qu'une corruption large, utilisez cet ordre :
- Commencez par la vérification évidente : Confirmez que vous déboguez la version de package attendue et la source.
- N'ayez pas confiance dans une purge de package spécifique trop : Une purge de nettoyage ciblée peut laisser des artefacts temporaires derrière elle.
- Passez à une purge de cache complète : Si la version obsolète persiste, nettoyez l'ensemble du champ de cache.
- Inspectez les chemins de cache temporaire manuellement : In installations plus anciennes,
cache/.tmppeut être le morceau manquant.
Lorsqu'un paquet se réfère toujours à une ancienne artefact, les fichiers de cache temporaires sont souvent la première place où je vérifierais après une tentative de nettoyage ciblé échouée.
Les problèmes de droits et d'environnement qui ressemblent à des problèmes de cache
Ce n'est pas tous les problèmes de cache qui sont des problèmes de contenu de cache.
Dans Docker, les systèmes Linux multi-utilisateurs ou les exécutants CI, vous pouvez rencontrer des erreurs de droits car le répertoire de cache est défini par un utilisateur différent de celui qui exécute Yarn. Dans ce cas, le nettoyage du cache ne servira à rien avant de résoudre le problème d'appartenance. La solution pratique est de lancer Yarn sous l'utilisateur correct, ou de réparer la propriété du répertoire avant de réinstaller.
Ces types d'issues se présentent souvent comme des caches périmés car les installations échouent de manière incohérente dans différents environnements. La solution est opérationnelle, et non liée au paquet.
Questions fréquemment posées sur le nettoyage du cache Yarn
Est-ce que nettoyer le cache Yarn est sécurisé
Oui. Dans le développement normal, c'est une opération sécurisée car vous supprimez des artefacts de paquets stockés en cache, et non votre source d'application. Yarn peut récupérer ce dont il a besoin à nouveau lors de la prochaine installation.
Le compromis est le temps. Un cache nettoyé signifie que la prochaine installation peut devoir télécharger ou reconstruire plus que d'habitude.
Combien de fois devriez-vous le faire
Seulement lorsque vous avez une raison.
Il ne faut pas faire régulièrement le nettoyage de la cache Yarn sur un projet en bonne santé. Si vous l'intégrez dans chaque workflow par habitude, vous ralentirez les installations locales et affaiblirez la mise en cache CI. Utilisez-le lorsque les dépendances sont obsolètes, les installations semblent corrompues ou que vous avez besoin d'un réglage délibéré pendant la débogage.
A-t-il un impact sur les builds de production
Non directement. Le nettoyage de votre cache local ou CI ne change pas l'application code que vous avez commit.
Ce qui change, c'est l'environnement qui prépare la build. Si votre pipeline de production dépend de l'artefact de mise en cache d'installation, le nettoyage de ceux-ci peut rendre les builds plus lents ou exposer des problèmes de reproductibilité cachés. C'est utile pendant la dépannage, mais ce n'est pas quelque chose à ajouter dans les scripts de mise en production sans une raison.
Quelle est la règle la plus simple à suivre
Utilisez la plus petite nettoyage qui correspond au problème.
Pour la débogage local, commencez par l'étendue de cache que Yarn utilise dans ce projet. Pour CI et Docker, corrigez la conception de la mise en cache avant de commencer à effacer les caches. Et lorsque la suppression de package spécifique ne fonctionne pas, supposez des artefacts temporaires ou un désalignement de l'environnement avant d'assumer que Yarn est cassé.
Si votre équipe livre des Capacitor applications et a besoin d'un pipeline de mise en production plus propre après des problèmes de dépendance ou de build, Capgo est une option pour livrer des mises à jour JavaScript et d'actifs sans attendre la revue de l'application, tout en gardant votre processus de build et de mise en production séparé de la dépanne de la mise en cache de package.
