Ejecutas yarn install, y la dependencia que acabas de actualizar sigue resolviendo a la build antigua. O tu laptop instala todo bien mientras que el CI falla de repente tras un cambio inofensivo en el lockfile. O las rebuilds de Docker tardan una eternidad, aunque estés “usando la caché”.
Es ahí cuando la gente suele buscar Limpiar la caché de Yarn y pegan el primer comando que encuentran.
A veces funciona. A veces no arregla nada. La razón es simple: el comportamiento de la caché de Yarn depende mucho de qué versión de Yarn estés usando, y la diferencia entre Yarn Classic v1 y Yarn Berry v2+ es suficiente para cambiar tanto el comando correcto como la estrategia de resolución de problemas.
La mayoría de las guías se quedan en yarn cache clean. Eso es solo el principio. Lo que importa es el alcance del cache, si tu proyecto usa un cache local o compartido, y si tu problema es realmente el cache. En CI y Docker, una mala estrategia de caching suele causar más problemas que los archivos de paquetes obsoletos.
Table of Contents
- Tu build está roto y el cache de Yarn podría ser el culpable
- Cuándo y por qué limpiar el cache de Yarn
- Cómo limpiar el cache en Yarn Classic v1
- Gestión de cache moderna en Yarn Berry v2+
- Buenas prácticas de Yarn Cache para CI/CD y Docker
- Solución de errores comunes de Yarn Cache
- Preguntas frecuentes sobre cómo limpiar el Yarn Cache
Tu build falló y el caché de Yarn podría ser el culpable
Este patrón te resultará familiar. Actualizas un paquete, descargas los últimos cambios y ejecutas install de nuevo. El comando termina, pero la app sigue comportándose como si la dependencia antigua estuviera presente. Alguien sugiere limpiar el caché y ahora te preguntas si es una solución real o solo superstición.
Puede ser una solución real. También puede ser una distracción.
Los problemas de caché suelen manifestarse de formas predecibles. Un paquete local no se actualiza. El CI descarga algo inesperado. Una rama nueva se comporta distinto a la principal aunque el lockfile diga que todo coincide. Si ya estás lidiando con inestabilidad en el pipeline, conviene combinar el debug del caché con una revisión de build más sistemática, como en esta guía sobre cómo arreglar fallos de build en pipelines de Capacitor CI/CD.
Regla práctica: Considera `yarn cache clean` como una herramienta de diagnóstico, no como un ritual de mantenimiento.
Lo complicado es que Yarn cambió su modelo de caché con el tiempo. En proyectos antiguos, el caché es global. En proyectos nuevos, la limpieza puede ser local, global o ambas, según los flags del comando. Así que cuando un compañero diga “solo limpia el caché de Yarn”, la primera pregunta debería ser: ¿Qué Yarn?
Por eso, una buena solución de caché empieza por el contexto. ¿Máquina local o CI runner? ¿Yarn v1 o Berry? ¿Caché compartida o del proyecto? Una vez que lo sepas, el comando será preciso en lugar de una apuesta.
Cuándo y por qué limpiar la caché de Yarn
Limpiar la caché de Yarn tiene sentido cuando tienes un fallo específico en mente. Es más útil cuando necesitas eliminar artefactos de paquetes obsoletos, recuperarte de una descarga corrupta o borrar deliberadamente paquetes almacenados para que Yarn reconstruya todo desde cero.
Síntomas que indican problemas de caché
Algunos casos claros para limpiar la caché:
- Una dependencia no se actualiza: Cambiaste la versión o reconstruiste un paquete local, pero las instalaciones siguen descargando un artefacto antiguo.
- Las instalaciones fallan como si dependieran del estado: Una máquina funciona, otra no, y al ejecutar el mismo comando se repite siempre el mismo error.
- Necesitas recuperar espacio en el disco local: Esto importa más en máquinas de desarrollo que en entornos de CI efímeros.
Otras situaciones solo parecen problemas de caché. Si tu lockfile cambió inesperadamente, si la configuración de un workspace es inconsistente o si un build de Docker invalida la capa incorrecta, limpiar la caché no solucionará la causa raíz. Los equipos que trabajan en builds de apps suelen encontrarse con esto al lidiar con herramientas nativas, dependencias de JavaScript y actualizaciones de plugins. En ese contexto, esta guía práctica sobre la gestión de dependencias en proyectos Capacitor vale la pena tener a mano.
Si tu objetivo es una limpieza general del sistema en lugar de solucionar problemas de paquetes, una guía a nivel de sistema también puede ayudar. Los desarrolladores de Mac que quieran limpiar cachés de apps para usuarios de Mac suelen descubrir que los gestores de paquetes son solo una parte del almacenamiento.
Cuándo no usar Yarn clear cache
No uses Yarn clear cache como primera respuesta ante cada problema de instalación.
Úsalo cuando haya indicios de que el estado de los paquetes está corrupto o desactualizado. Omítelo si el problema probablemente sea:
| Situación | Mejor primer paso |
|---|---|
| Desajuste del lockfile | Revisa los yarn.lock cambios y reinstala de forma consistente |
| Problemas de resolución en el workspace | Revisa la config del workspace y el comportamiento de install |
| Lentitud al reconstruir Docker | Revisa el orden de las capas y la persistencia del cache |
| Desajuste en CI | Verifica qué directorios se restauran realmente |
Si la instalación falla por un entorno incorrecto, limpiar el cache solo hará que la siguiente instalación errónea sea más lenta.
Esa distinción ahorra tiempo. Mucho tiempo de debugging se pierde tratando el cache como un botón de reset mágico.
Cómo limpiar el cache en Yarn Classic v1
Yarn Classic se comporta como muchos desarrolladores aún creen que funcionan todas las versiones de Yarn. Utiliza un cache global en el directorio de usuario y yarn cache clean limpia ese cache compartido. La propia documentación de Yarn Classic lo describe así y señala que el cache se vuelve a llenar en la siguiente yarn o yarn install ejecución según el modelo de directorio de usuario documentado en la documentación de CLI del cache de Yarn Classic.
Lo que el comando elimina realmente
Para Yarn v1, el comando de limpieza por defecto es sencillo:
yarn cache clean
Ese comando borra el cache compartido, no solo el del proyecto actual. Si trabajas en varios repositorios en la misma máquina, esto importa. La siguiente instalación en cualquiera de ellos podría requerir descargar los paquetes de nuevo.
Este diseño de cache compartido es una razón por la que Yarn v1 puede causar comportamientos confusos entre proyectos. Un artefacto obsoleto en el cache global puede persistir lo suficiente como para afectar a distintos repos, especialmente en desarrollo de paquetes locales.
Una secuencia práctica para Yarn Classic suele ser así:
- Primero, ejecuta el comando clean:
yarn cache clean - Remove local install artifacts if needed:
node_modulessuele ser el siguiente paso si el estado sigue siendo inconsistente. - Reinstala desde cero: Ejecuta
yarn installde nuevo y confirma que el grafo de dependencias se resuelva correctamente.
Cómo verificar la ubicación del cache
Cuando quieras inspeccionar o borrar el directorio de cache directamente, Yarn Classic te da la ruta:
yarn cache dir
Esto es útil cuando el comando CLI no parece solucionar el problema, o cuando necesitas confirmar qué cuenta de usuario es dueña del directorio de cache en un entorno compartido o contenedorizado.
Si trabajas con un toolchain antiguo y buscas que tu configuración local sea predecible, esta guía sobre cómo instalar Capacitor CLI paso a paso combina perfecto con un reset de dependencias limpio.
Inspeccionar el caché manualmente suele ser más útil que ejecutar un segundo comando de limpieza a ciegas.
Para proyectos v1, el modelo mental es simple. Un caché compartido, un comando de limpieza general y la siguiente instalación repuebla lo que eliminaste.
Gestión de caché moderna en Yarn Berry v2+
Yarn Berry cambió las reglas del juego. Si vienes de Yarn v1, el mayor ajuste es que limpiar el caché ya no es solo "borrar el store global e intentar de nuevo". Berry permite un control más preciso, algo muy útil cuando sabes exactamente qué quieres atacar.
Berry cambió el modelo de caché
En el Yarn moderno, el comportamiento del caché está mucho más ligado al proyecto mismo. Esto encaja con el enfoque de Berry hacia el control a nivel de proyecto, Plug’n’Play y workflows donde las dependencias viven junto al repo en lugar de un modelo de caché único para toda la máquina.
Por eso los consejos antiguos pueden confundirte. Un compañero que aprendió Yarn en v1 podría esperar un comando para purgar todo globalmente. En Berry, debes pensar en términos de alcance.
Si manejas distintos outputs de build en pipelines de mobile y web, esa misma mentalidad de alcance se aplica fuera del package management. Esta comparativa de tipos de builds es un recordatorio útil de que los supuestos del entorno suelen afectar al debugging.
Aquí tienes una breve explicación visual antes de ver los detalles del comando:
Los comandos clave en Berry
La documentación de Yarn moderno yarn cache clean como eliminar archivos de caché compartidos, y expone dos flags importantes en la referencia actual del comando yarn cache clean:
yarn cache cleanelimina los archivos de caché compartidos de Yarn.yarn cache clean --mirrorlimpia la caché global en lugar de la caché local del proyecto.yarn cache clean --allelimina tanto los archivos de la caché global como los de la caché local del proyecto actual.
Eso te ofrece un flujo de trabajo más preciso que en Yarn v1.
| Objetivo | Comando |
|---|---|
| Limpiar el scope del cache compartido por defecto | yarn cache clean |
| Apuntar al cache del mirror global | yarn cache clean --mirror |
| Hacer un reset completo de los archivos de cache locales y globales | yarn cache clean --all |
Usa --all cuando busques el equivalente a “empezar de cero”. Usa --mirror cuando sepas que el problema está en la capa del cache global y no quieras borrar todo el proyecto.
Punto de decisión: En Berry, elegir el scope incorrecto es una de las razones principales por las que limpiar la caché parece no hacer nada.
Esa es la diferencia práctica. Yarn Classic era amplio por defecto. Berry es explícito por diseño.
Mejores prácticas de Yarn Cache para CI/CD y Docker
En CI/CD, borrar la caché de Yarn a ciegas suele ser un error. Parece seguro porque elimina el estado, pero a menudo borra el mismo estado del que depende tu pipeline para ganar velocidad y repetibilidad.
La pregunta realmente útil es esta: ¿qué estás cacheando exactamente y qué estás restaurando exactamente?
Por qué borrar la caché en los pipelines suele ser una mala decisión
Una discusión en CircleCI capturó un patrón de fallo que muchos equipos encuentran en proyectos reales. Las instalaciones lentas no se arreglaban limpiando la caché porque el cuello de botella no eran archivos de paquetes obsoletos. Era el comportamiento de fetch y link, desajustes en el directorio de caché y rutas faltantes node_modules en el conjunto cacheado, tal como se describe en ese Hilo de caché de Yarn en CircleCI.
Eso importa porque los sistemas de CI suelen ocultar la causa raíz tras un síntoma vago: “la instalación es lenta” o “el paso de dependencias falla de forma intermitente”. Los desarrolladores entonces borran la caché, reintentan y no ven ninguna mejora real.
Errores comunes en pipelines:
- Cachear el directorio incorrecto: El paso de restauración termina, pero Yarn no utiliza la ubicación restaurada.
- Ignorar rutas del workspace: Las dependencias raíz pueden restaurarse mientras el workspace aún requiere relinkear.
- Construir capas de Docker en el orden incorrecto: Una copia de code invalida la capa de dependencias, forzando la instalación de paquetes cada vez.
En CI, un cache miss causado por una mala configuración se parece mucho a un cache corrupto.
Si construyes apps móviles en entornos automatizados, aquí es donde entra el tooling de release. Los equipos suelen combinar GitHub Actions o CircleCI con sistemas de distribución y update. Una opción en ese workflow es el setup de CI/CD de Capgo para apps Capacitor, junto a tu estrategia de build-cache y package-manager.
Un mejor enfoque para CI y Docker
Usa la invalidación de caché con criterio, no por impulso.
Para CI, un patrón confiable es este:
- Caché basado en el estado de las dependencias: Vincula las claves de caché a
yarn.locky los archivos de configuración de Yarn pertinentes. - Restaura antes de instalar: Asegúrate de que las rutas restauradas coincidan con las que Yarn usará en ese entorno.
- Instala de forma consistente: En entornos inmutables, usa el modo de instalación que fuerce la integridad del lockfile.
- Invalida ante cambios reales: Un cambio de versión de Yarn, una actualización del lockfile o un cambio en la ruta de caché justifican reconstruir la caché.
Para Docker, los principios son similares:
- Copia primero los manifiestos de dependencias: Mantén la capa de instalación de dependencias separada del código fuente de la app cuando sea posible.
- Evita limpiezas innecesarias al construir la imagen: Borrar la caché en el mismo build suele eliminar la reutilización de capas útiles.
- Sé explícito con la propiedad del usuario: Directorios de caché creados por root pueden causar fallos de instalación para un usuario de runtime sin privilegios.
Una tabla de decisiones rápida ayuda:
| Escenario | Mejor acción que yarn cache clean |
|---|---|
| La instalación en CI es lenta tras el restore | Verifica la ruta de caché y el orden de restore |
| Los workspaces siguen requiriendo mucho relink | Cachea los artifacts de instalación del workspace relevante |
| Reconstruir Docker vuelve a ejecutar las instalaciones | Reorder layers around dependency files |
| Un build fallido tras cambiar dependencias | Invalida la cache key y reconstruye de cero |
Usa Yarn clear cache en CI solo si confirmas que el contenido obsoleto de la cache es el problema real. La mayoría de las veces, la solución es un mejor diseño de la cache.
Solución de errores comunes de la cache de Yarn
El bug de cache más frustrante es el que sobrevive a una limpieza. Ejecutas un cleanup específico, reinstalas y Yarn sigue bajando el paquete viejo. En ese punto, es tentador pensar que el registry está mal o que el lockfile está maldito.
Un problema histórico documentado en Yarn explica por qué sucede esto. Los desarrolladores reportaron que yarn cache clean <package-name> podía dejar una copia antigua en cache/.tmp, lo que significaba que las instalaciones seguían usando la versión obsoleta hasta que se borraba ese directorio temporal o se ejecutaba un cleanup completo, como se discute en el issue de Yarn sobre artefactos de cache obsoletos en .tmp.
Cuando un clean específico deja paquetes obsoletos
La lección es simple. Un clean parcial no siempre es suficiente.
Si sospechas de versiones obsoletas en lugar de una corrupción general, sigue este orden:
- Empieza con la comprobación obvia: Confirma que estás depurando la versión del paquete y la fuente correctas.
- No confíes demasiado en una limpieza específica de un paquete: Una limpieza selectiva puede dejar artefactos temporales atrás.
- Escala a un borrado completo de la caché: Si la versión antigua persiste, limpia el caché de forma más amplia.
- Inspect temp cache paths manually: En configuraciones antiguas,
cache/.tmppuede ser la pieza que falta.
Cuando un paquete sigue resolviendo a un artefacto antiguo, los archivos de caché temporal suelen ser lo primero que reviso tras una limpieza selectiva fallida.
Problemas de permisos y de entorno que parecen fallos de caché
No todos los “errores de caché” son problemas de contenido.
En Docker, sistemas Linux multiusuario o runners de CI, puedes encontrar fallos de permisos porque el directorio de caché pertenece a un usuario distinto al proceso que ejecuta Yarn. En ese caso, limpiar la caché no servirá de nada hasta que arregles la propiedad de los archivos. Lo práctico es ejecutar Yarn con el usuario correcto o reparar los permisos del directorio antes de reinstalar.
Ese tipo de problema suele parecer un caché desactualizado porque las instalaciones fallan de forma inconsistente entre entornos. La solución es operativa, no relacionada con el paquete.
Preguntas frecuentes sobre cómo limpiar la caché de Yarn
¿Es seguro limpiar la caché de Yarn?
Sí. En un flujo de desarrollo normal es una operación segura porque estás eliminando artefactos de paquetes en caché, no borrando el código fuente de tu aplicación. Yarn volverá a descargar lo que necesite en la siguiente instalación.
El compromiso es el tiempo. Un caché limpio significa que la siguiente instalación podría necesitar descargar o reconstruir más de lo habitual.
¿Con qué frecuencia debería hacerse?
Solo cuando haya una razón justificada.
Limpiar la caché de Yarn no debería ser un mantenimiento rutinario en un proyecto sano. Si lo incluyes en cada workflow por costumbre, ralentizarás las instalaciones locales y afectarás el caching de tu CI. Úsalo cuando las dependencias estén obsoletas, las instalaciones parezcan corruptas o necesites un reset deliberado durante el debugging.
¿Afectará a los builds de producción?
No directamente. Limpiar tu caché local o de CI no cambia el code de la aplicación que has commiteado.
Lo que sí cambia es el entorno que prepara el build. Si tu pipeline de producción depende de artefactos de instalación en caché, borrarlos puede ralentizar los builds o sacar a la luz problemas de reproducibilidad ocultos. Eso es útil durante el troubleshooting, pero no es algo que debas meter en los scripts de release sin motivo.
¿Cuál es la regla práctica más sencilla que seguir?
Usa la limpieza más pequeña que se ajuste al problema.
Para debugging local, empieza con el scope de caché que Yarn usa en ese proyecto. Para CI y Docker, ajusta el diseño de la caché antes de empezar a borrar cachés. Y si una limpieza específica de un paquete no funciona, asume que hay artefactos temporales o un mismatch de entorno antes de pensar que Yarn está roto.
Si tu equipo lanza apps con Capacitor y necesita un pipeline de release más limpio tras problemas de dependencias o build, Capgo es una opción para entregar actualizaciones de JavaScript y assets sin esperar a la revisión de las tiendas, manteniendo tu proceso de build y rollout separado del troubleshooting de la caché de paquetes.
