Limpiar la caché de Laravel: qué comando usar y cuándo

Hola, ¿cómo están? Esta lección es corta, pero probablemente sea la que más veces vas a volver a consultar.

Cambias algo en el .env y no pasa nada. Añades una ruta y da 404. Editas una vista y sigue viéndose la anterior. En casi todos esos casos, la respuesta es la misma: está en caché.

Vamos a ver qué guarda cada caché, qué comando la limpia y cuándo usar cada uno.

¡Empecemos!

Los comandos, de un vistazo

php artisan config:clear      # configuración y .env
php artisan route:clear       # rutas
php artisan view:clear        # vistas Blade compiladas
php artisan cache:clear       # datos de la aplicación
php artisan event:clear       # eventos y listeners
php artisan optimize:clear    # todo lo anterior de una vez

Si tienes prisa, optimize:clear resuelve el 90% de los casos. Pero conviene entender qué hace cada uno, porque en producción no siempre quieres borrarlo todo.

config:clear — el que más falta hace

Guarda: todos los archivos de config/ combinados en uno solo, con los valores del .env ya resueltos.

Cuándo limpiarla: cada vez que cambies el .env o cualquier archivo de config/.

php artisan config:clear

Este es el responsable de la mayoría de confusiones. Cambias MAIL_MAILER, DB_DATABASE o APP_LOCALE, recargas, y el sistema sigue usando el valor anterior. No hay ningún error; simplemente ignora el cambio.

Y hay una consecuencia que conviene conocer: cuando la configuración está en caché, la función env() deja de funcionar fuera de config/.

// MAL: en un controlador, devuelve null si la config está cacheada
$clave = env('SERVICIO_API_KEY');

// BIEN
$clave = config('servicios.api_key');

// config/servicios.php
return [
    'api_key' => env('SERVICIO_API_KEY'),
];

La regla: env() solo dentro de config/. En el resto del código, siempre config(). Es de esos fallos que funcionan perfectamente en local y explotan en producción, porque en producción sí se cachea la configuración.

route:clear

Guarda: todas las rutas del proyecto en un archivo optimizado.

Cuándo limpiarla: al añadir, cambiar o eliminar rutas, si las tenías cacheadas.

php artisan route:clear

Síntoma típico: creas una ruta nueva y da 404, o route('pacientes.papelera') lanza un error de ruta no definida aunque esté ahí.

Para ver las rutas activas:

php artisan route:list
php artisan route:list --path=pacientes
php artisan route:list --except-vendor

La caché de rutas no admite closures. Si tienes rutas con función anónima, route:cache falla:

// no se puede cachear
Route::get('/prueba', function () {
    return 'hola';
});

// sí se puede
Route::get('/prueba', [PruebaController::class, 'index']);

Es una razón más para usar controladores, como vimos en la lección de rutas.

view:clear

Guarda: las plantillas Blade compiladas a PHP, en storage/framework/views/.

Cuándo limpiarla: casi nunca, porque Blade recompila sola cuando detecta que el archivo cambió.

php artisan view:clear

Sirve cuando algo se descuadra: cambias una vista y sigue apareciendo la anterior, o después de copiar archivos entre máquinas con fechas raras.

Y también libera espacio, porque esa carpeta crece bastante con el tiempo.

cache:clear

Guarda: lo que tú guardes desde el código.

Cache::put('total_pacientes', $total, now()->addHour());
Cache::get('total_pacientes');

$reporte = Cache::remember('reporte_mensual', 3600, function () {
    return Cita::selectRaw('estado, count(*) as total')
        ->groupBy('estado')
        ->get();
});

Ese remember() es el patrón más útil: si el valor está en caché lo devuelve; si no, ejecuta la consulta, la guarda y la devuelve.

php artisan cache:clear

Cuidado en producción. Ese comando borra toda la caché de la aplicación, y si el sistema depende de ella para consultas pesadas, la siguiente carga las recalcula todas de golpe.

Para borrar solo una clave:

Cache::forget('reporte_mensual');

Y para agrupar y borrar por conjuntos —según el controlador de caché que uses:

Cache::tags(['reportes'])->flush();

Un detalle importante: cache:clear también borra las sesiones si SESSION_DRIVER apunta al mismo almacén. Todos los usuarios quedarían desconectados. Vale la pena revisarlo antes de ejecutarlo en un sistema con gente trabajando.

Las cachés que también existen

php artisan event:clear        # eventos y listeners descubiertos
php artisan queue:restart      # reiniciar los procesos de cola
php artisan schedule:clear-cache

Ese queue:restart es fácil de olvidar y muy desconcertante: los procesos de cola cargan el código una vez y lo mantienen en memoria. Si despliegas cambios y no los reinicias, siguen ejecutando la versión anterior indefinidamente.

Lo veremos con más detalle en la lección de colas, pero conviene tenerlo presente desde ya.

optimize:clear

php artisan optimize:clear

Ejecuta todos los clear de una vez. Es lo que uso en desarrollo cuando algo no cuadra y no quiero pensar cuál es.

El otro lado: cachear en producción

En desarrollo limpias. En producción haces lo contrario:

php artisan optimize

Eso cachea la configuración y las rutas, y mejora de forma notoria el tiempo de respuesta, porque Laravel deja de leer y combinar decenas de archivos en cada petición.

Los comandos por separado:

php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan event:cache

En desarrollo, no caches nada. Si ejecutas config:cache en local, vas a pasar la tarde preguntándote por qué el .env no hace efecto.

La secuencia al desplegar

Esta es la parte práctica de la lección. Al subir cambios al servidor:

php artisan down                     # modo mantenimiento

git pull origin main
composer install --no-dev --optimize-autoloader

php artisan migrate --force

php artisan optimize:clear           # limpiar lo viejo
php artisan optimize                 # cachear lo nuevo

php artisan queue:restart            # recargar los trabajadores

php artisan up                       # volver a levantar

El orden importa: primero limpiar, después cachear. Al revés, cacheas y luego borras lo que acabas de cachear.

Y ese --force en migrate es obligatorio en producción; sin él, Artisan pide confirmación interactiva y el despliegue automatizado se queda esperando.

Lo desarrollamos completo en la lección de despliegue.

Guía rápida de síntomas

Lo que ves	Lo que suele ser
El .env no hace efecto	config:clear
Ruta nueva da 404	route:clear
route() dice que no existe	route:clear
La vista muestra lo anterior	view:clear
env() devuelve null	Config cacheada: usa config()
Los datos siguen desactualizados	cache:clear
El trabajador de cola usa código viejo	queue:restart
El correo va al servidor anterior	config:clear
Nada tiene sentido	optimize:clear

Cuando limpiar no basta

A veces el problema no es la caché de Laravel:

composer dump-autoload

Si creaste una clase nueva y PHP dice que no existe, es el autocargador. Pasa sobre todo al mover archivos entre carpetas.

Y en servidores con OPcache activado, el código PHP compilado también se guarda en memoria. Ahí hace falta reiniciar PHP-FPM:

sudo systemctl reload php8.4-fpm

Si limpiaste todas las cachés de Laravel y el código antiguo sigue ejecutándose, casi siempre es OPcache.

Una advertencia sobre permisos

Si un comando de caché falla con un error de permisos, es que las carpetas de escritura no son accesibles para el servidor web:

chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

Esas dos carpetas son las únicas que Laravel necesita escribir.

Errores comunes

• env() fuera de config/, que devuelve null en producción.
• config:cache en desarrollo, y horas perdidas con el .env.
• Desplegar sin queue:restart, dejando los trabajadores con código viejo.
• cache:clear en producción sin pensar en las sesiones.
• Cachear después de limpiar en lugar de al revés.
• Buscar el problema en Laravel cuando es OPcache o el autocargador.

Para cerrar

Si te quedas con tres cosas de esta lección:

optimize:clear cuando algo no cuadra en desarrollo. optimize al desplegar en producción. Y config() en lugar de env() fuera de la carpeta de configuración.

Ese último punto no es una preferencia de estilo: es la diferencia entre un sistema que funciona en producción y uno que falla sin explicación aparente.

Con esta lección cerramos el módulo. En la siguiente empezamos con Laravel avanzado, viendo el contenedor de servicios y la inyección de dependencias.

Saludos y éxitos.