Ejecutas yarn install, y la dependencia que acabas de actualizar sigue resolviendo a la build antigua. O tu laptop instala sin problemas mientras que el CI falla de repente tras un cambio inofensivo en el lockfile. O los rebuilds de Docker se alargan, aunque estés "usando la caché".
Es ahí cuando la gente suele buscar Limpiar la caché de Yarn y pega el primer comando que encuentra.
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 lo suficientemente grande como para cambiar tanto el comando correcto como la estrategia de solución de problemas.
La mayoría de las guías se detienen en yarn cache clean. Eso es solo el principio. Lo importante es el alcance de la caché, si tu proyecto usa una caché local o compartida, y si tu problema real es siquiera la caché. En CI y Docker, una mala estrategia de caché suele causar más problemas que los archivos de paquetes obsoletos.
Tabla de contenidos
- Tu build está roto y la caché de Yarn podría ser la culpable
- Cuándo y por qué limpiar tu caché de Yarn
- Limpiar la caché en Yarn Classic v1
- Gestión moderna de caché en Yarn Berry v2+
- Buenas prácticas de caché de Yarn para CI/CD y Docker
- Solución de errores comunes de caché de Yarn
- Preguntas frecuentes sobre la limpieza de la caché de Yarn
Tu build está roto y la caché de Yarn podría ser la culpable
Un patrón familiar se ve así. Actualizas un paquete, tiras de cambios nuevos y vuelves a ejecutar install. El comando termina, pero la app sigue comportándose como si la dependencia antigua estuviera presente. Entonces alguien sugiere limpiar la 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 unas pocas formas predecibles. Un paquete local no se actualiza. CI tira de algo inesperado. Una rama nueva se comporta de forma diferente a la rama principal, aunque el lockfile indique que todo debería coincidir. Si ya estás persiguiendo una inestabilidad más amplia en el pipeline, ayuda combinar el debug de caché con una revisión de build más sistemática, como esta guía sobre corregir fallos de build en pipelines CI/CD de Capacitor.
Regla práctica: Usa Yarn clear cache como herramienta de diagnóstico, no como ritual de mantenimiento.
Lo complicado es que Yarn cambió su modelo de caché con el tiempo. En proyectos antiguos, la caché es global y compartida. En proyectos más nuevos, la limpieza de la caché puede ser local al proyecto, global o ambas, dependiendo de las flags del comando. Así que cuando un compañero dice “solo limpia la 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 de proyecto? Una vez que lo sepas, el comando será preciso en lugar de una apuesta.
Cuándo y por qué limpiar tu 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 los paquetes almacenados para que Yarn reconstruya desde cero.
Síntomas que indican problemas de caché
Algunos casos son candidatos claros para limpiar la caché:
- Una dependencia se niega a actualizarse: Cambiaste la versión, o reconstruiste un paquete local, pero las instalaciones siguen trayendo un artefacto antiguo.
- Las instalaciones fallan como si dependieran del estado: Una máquina funciona, otra no, y volver a ejecutar el mismo comando sigue dando el mismo resultado erróneo.
- Necesitas liberar 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ó de forma inesperada, si la configuración de un workspace es inconsistente o si un build de Docker invalida la capa equivocada, limpiar la caché no resolverá la causa raíz. Los equipos que trabajan con builds de apps suelen toparse con esto mientras lidian con herramientas nativas, dependencias de JavaScript y actualizaciones de plugins. En ese contexto, este repaso práctico de gestionar dependencias en proyectos de Capacitor vale la pena tenerlo a mano.
Si tu objetivo es una limpieza general de la máquina y no solo resolver problemas de paquetes, una guía a nivel de sistema también puede ayudar. Desarrolladores de Mac que quieren limpiar las cachés de apps para usuarios de Mac a menudo descubren que los gestores de paquetes son solo una parte del panorama de almacenamiento.
Cuándo no recurrir a Yarn clear cache
No uses Yarn clear cache como primera respuesta a cada problema de instalación.
Úsalo cuando haya indicios de un estado de los paquetes obsoleto o corrupto. Omítelo si el problema probablemente sea:
| Situación | Mejor primer paso |
|---|---|
| Desfase del lockfile | Revisión yarn.lock cambia y reinstala de forma consistente |
| Problemas de resolución del workspace | Check workspace config and install behavior |
| Lentitud al reconstruir Docker | Revisa el orden de las capas y la persistencia de la caché |
| Desajuste en CI | Verifica qué directorios se restauran realmente |
Si la instalación está mal porque el entorno está mal, limpiar la caché solo hace más lenta la próxima instalación incorrecta.
Esa distinción ahorra tiempo. Gran parte del debugging desperdiciado viene de tratar la caché como un botón mágico de reinicio.
Limpiar la caché en Yarn Classic v1
Yarn Classic se comporta como muchos desarrolladores todavía asumen que lo hacen todas las versiones de Yarn. Usa una caché global en el directorio de usuario y yarn cache clean limpia esa caché compartida. La propia documentación de Yarn Classic lo describe así y señala que la caché se repuebla en la próxima yarn o yarn install ejecución en el modelo de directorio de usuario documentado en la documentación de la caché de Yarn Classic CLI.
Lo que elimina realmente el comando
Para Yarn v1, el comando de limpieza predeterminado es sencillo:
yarn cache clean
Ese comando borra la caché compartida, no solo la del proyecto actual. Si trabajas en varios repositorios en la misma máquina, esto importa. La próxima instalación en cualquiera de ellos podría necesitar volver a descargar paquetes.
Este diseño de caché compartida es una de las razones por las que Yarn v1 puede generar comportamientos confusos entre proyectos. Un artefacto obsoleto en la caché global puede sobrevivir lo suficiente como para afectar a repositorios distintos, especialmente cuando se involucra el desarrollo de paquetes locales.
Una secuencia práctica para Yarn Classic suele ser así:
- Ejecuta primero el comando de limpieza:
yarn cache clean - Elimina los artefactos de instalación local si es necesario:
node_modulessuele ser el siguiente candidato cuando el estado sigue pareciendo inconsistente. - Reinstala desde cero: Ejecuta
yarn installnuevamente y confirmar que el grafo de dependencias se resuelve como se espera.
Cómo verificar la ubicación de la caché
Cuando quieras inspeccionar o eliminar directamente el directorio de caché, Yarn Classic te da la ruta:
yarn cache dir
Eso es útil cuando el comando CLI no parece resolver el problema, o cuando necesitas confirmar qué cuenta de usuario es dueña del directorio de caché en un entorno compartido o en contenedores.
Si trabajas con una toolchain antigua y quieres mantener la configuración local predecible, esta guía sobre instalar Capacitor CLI paso a paso combina bien con un reinicio limpio de dependencias.
Una inspección manual de la caché suele valer más que un segundo comando de limpieza a ciegas.
Para proyectos v1, el modelo mental es simple. Una caché compartida, un comando de limpieza amplio y la siguiente instalación repuebla lo que eliminaste.
Gestión moderna de caché en Yarn Berry v2+
Yarn Berry cambió el panorama. Si vienes de Yarn v1, el mayor cambio es que la limpieza de caché ya no es solo «borrar el almacén global y volver a intentarlo». Berry permite un control más preciso, lo cual es útil una vez que sabes a qué apuntar.
Berry cambió el modelo de caché
En Yarn moderno, el comportamiento de la caché está mucho más ligado al propio proyecto. Esto encaja con el enfoque más amplio de Berry: control a nivel de proyecto, Plug’n’Play y flujos de trabajo donde las dependencias pueden convivir con el repositorio en lugar de en un modelo de caché global para toda la máquina.
Por eso los consejos antiguos pueden engañarte. Un compañero que aprendió Yarn en v1 puede esperar que un solo comando lo purgue todo globalmente. En Berry, tienes que pensar en términos de alcance.
Si te enfrentas a distintos resultados de build en pipelines móviles y web, esa misma mentalidad de alcance también aplica fuera de la gestión de paquetes. Esta comparación de tipos de builds es un recordatorio útil de que las suposiciones sobre el entorno suelen afectar al debugging.
Aquí tienes una breve explicación visual antes de ver los detalles del comando:
Los comandos clave en Berry
Yarn moderno documenta 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 workflow más preciso que en Yarn v1.
| Objetivo | Comando |
|---|---|
| Limpia el ámbito de caché compartida predeterminado | yarn cache clean |
| Apunta a la caché espejo global | yarn cache clean --mirror |
| Haz un reset completo de los archivos de caché locales y globales | yarn cache clean --all |
Usa --all cuando quieras el equivalente más cercano a “empezar de cero”. Usa --mirror cuando sepas que el problema está en la capa de caché global y no quieras borrar todo en el proyecto.
Punto de decisión: En Berry, elegir el scope equivocado es una de las principales razones por las que una limpieza de 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 caché de Yarn 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 recogió un patrón de fallo con el que muchos equipos se topan en proyectos reales. Las instalaciones lentas no se arreglaban limpiando la caché porque el cuello de botella no eran los 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 subyacente tras un síntoma vago: “la instalación es lenta” o “el paso de dependencias falla de forma intermitente”. Entonces los desarrolladores borran la caché, vuelven a ejecutar y no obtienen ninguna mejora real.
Errores comunes en los pipelines:
- Cachear el directorio incorrecto: El paso de restauración termina, pero Yarn no utiliza la ubicación restaurada.
- Ignorando rutas de workspace: Las dependencias raíz pueden restaurarse mientras el trabajo de instalación del workspace aún debe relinkarse.
- Construyendo capas de Docker en el orden incorrecto: Una copia de origen code invalida la capa de dependencias, por lo que la instalación de paquetes se vuelve a ejecutar cada vez.
En CI, un fallo de caché causado por una mala configuración se parece mucho a una caché corrupta.
Si estás construyendo apps móviles en entornos automatizados, aquí es donde entran en juego las herramientas de release. Los equipos suelen combinar GitHub Actions o CircleCI con sistemas de distribución y actualización. Una opción en ese flujo más amplio es Configuración de CI/CD de Capgo para apps de Capacitor, junto a tu estrategia de gestor de paquetes y caché de build.
Un mejor enfoque de CI y Docker
Usa la invalidación de caché de forma deliberada, no emocional.
Para CI, un patrón fiable se ve así:
- Caché basada en el estado de las dependencias: Vincula las claves de caché con
yarn.locky los archivos de configuración de Yarn relevantes. - Restaura antes de instalar: Asegúrate de que las rutas restauradas coincidan con las que usará Yarn en ese entorno.
- Instala de forma consistente: En configuraciones inmutables, usa el modo de instalación que fuerza la corrección del lockfile.
- Invalida ante cambios reales: Un cambio en la versión de Yarn, una actualización del lockfile o un cambio en la ruta de caché son buenas razones para 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 de la aplicación cuando sea posible.
- Evita limpiezas innecesarias en el build de la imagen: Eliminar la caché dentro del mismo build suele eliminar la reutilización útil de capas.
- Sé explícito sobre la propiedad de usuario: Los directorios de caché creados por root pueden causar fallos de instalación posteriores para un usuario de runtime no root.
Una tabla de decisiones breve ayuda:
| Escenario | Mejor acción que yarn cache clean |
|---|---|
| La instalación en CI es lenta tras el restore | Verifica la ruta de la caché y el orden de restore |
| Los workspaces siguen relinkeando mucho | Cachea los artefactos de instalación relevantes del workspace |
| Docker rebuild vuelve a ejecutar las instalaciones | Reordenar capas alrededor de los archivos de dependencias |
| Un build fallido tras cambiar una dependencia | Invalida la clave de caché y reconstruye desde cero |
Usa Yarn clear cache en CI solo cuando hayas confirmado que el contenido obsoleto de la caché es el problema real. La mayoría de las veces, la solución es un mejor diseño de caché.
Solución de errores comunes de caché de Yarn
El bug de caché más frustrante es el que sobrevive a una limpieza de caché. Haces una limpieza específica, reinstalas y Yarn sigue descargando 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é ocurre. Los desarrolladores reportaron que yarn cache clean <package-name> podía dejar una copia antigua en cache/.tmp, lo que hacía que las instalaciones siguieran usando la versión obsoleta hasta eliminar ese directorio temporal o ejecutar una limpieza completa, como se explica en el issue de Yarn sobre artefactos de caché obsoletos en .tmp.
Cuando una limpieza específica aún deja paquetes obsoletos
La lección es simple. Una limpieza parcial no siempre es suficiente.
Si sospechas de una versión desactualizada en lugar de una corrupción general, usa este orden:
- Empieza con la comprobación obvia: Confirma que estás depurando la versión y la fuente del paquete esperadas.
- No confíes demasiado en una limpieza específica del paquete: Una limpieza dirigida puede dejar artefactos temporales atrás.
- Escala a una limpieza completa de la caché: Si la versión desactualizada persiste, limpia el alcance más amplio de la caché.
- Inspect temp cache paths manually: En configuraciones antiguas,
cache/.tmppuede ser la pieza que faltaba.
Cuando un paquete sigue resolviéndose a un artefacto antiguo, los archivos de caché temporal suelen ser el primer lugar que inspecciono tras un clean dirigido fallido.
Problemas de permisos y entorno que parecen problemas de caché
No todo “error de caché” es un problema de contenido de caché.
En Docker, sistemas Linux multiusuario o runners de CI, puedes encontrar fallos de permisos porque el directorio de caché pertenece a un usuario diferente al proceso que ejecuta Yarn. En ese caso, limpiar la caché no ayudará hasta que se solucione el problema de propiedad. La solución práctica es ejecutar Yarn como el usuario correcto o reparar la propiedad del directorio antes de reinstalar.
Ese tipo de problema suele presentarse como caché obsoleta porque las instalaciones fallan de forma inconsistente entre entornos. La solución es operativa, no relacionada con el paquete.
Preguntas frecuentes sobre la limpieza de la caché de Yarn
¿Es seguro limpiar la caché de Yarn?
Sí. En el desarrollo normal, es una operación segura porque eliminas artefactos de paquetes en caché, no el código fuente de tu aplicación. Yarn puede volver a obtener lo que necesite en la siguiente instalación.
El contratiempo es el tiempo. Una caché limpia significa que la siguiente instalación puede necesitar descargar o reconstruir más de lo habitual.
¿Con qué frecuencia debes hacerlo?
Solo cuando tengas una razón.
Limpiar la caché de Yarn no debería ser mantenimiento rutinario en un proyecto sano. Si lo incluyes en cada workflow por costumbre, ralentizarás las instalaciones locales y comprometerás la caché de CI. Úsalo cuando las dependencias estén desactualizadas, las instalaciones parezcan corruptas o necesites un reinicio deliberado durante la depuración.
¿Afectará a las compilaciones de producción?
No directamente. Limpiar tu caché local o de CI no cambia la aplicación code que has commitado.
Lo que sí cambia es el entorno que prepara la compilación. Si tu pipeline de producción depende de artefactos de instalación en caché, limpiarlos puede hacer que las compilaciones sean más lentas o exponer problemas ocultos de reproducibilidad. Eso es útil durante la solución de problemas, pero no es algo que debas esparcir por los scripts de liberación sin una razón.
¿Cuál es la regla práctica más simple a seguir?
Usa la limpieza más pequeña que se ajuste al problema.
Para la depuración local, empieza con el alcance de caché que Yarn usa en ese proyecto. Para CI y Docker, corrige el diseño de la caché antes de empezar a borrar cachés. Y cuando una limpieza específica de un paquete no funcione, asume artefactos temporales o un desajuste de entorno antes de asumir que Yarn está roto.
Si tu equipo publica apps de Capacitor y necesita un pipeline de releases más limpio tras problemas de dependencias o build, Capgo es una opción para entregar actualizaciones de JavaScript y assets sin esperar la revisión de la tienda, manteniendo tu proceso de compilación y despliegue separado de la solución de problemas de la caché de paquetes.
