El modo depuración se ajusta con APP_DEBUG en el fichero .env: true en local, false en producción, siempre. Comprueba el estado real con php artisan about --only=environment. Si el cambio no surte efecto, la configuración está en caché: lanza php artisan config:clear.
El modo depuración decide lo que ve un visitante cuando tu aplicación revienta: el stack trace completo con el código fuente y las variables de entorno, o una página de error neutra. Es un ajuste de una línea, pero también una de las fugas de datos más habituales en producción.
Artículo del itinerario Desarrollo web. Verificado en Laravel 13.30.1 con PHP 8.4.25.
Activar y desactivar
El ajuste se hace en el fichero .env, en la raíz del proyecto, y en ningún otro sitio:
APP_ENV=local
APP_DEBUG=truePara desactivarlo, pon el valor a false:
APP_ENV=production
APP_DEBUG=falseComprueba el estado efectivo sin escribir una sola línea de código:
php artisan about --only=environment Environment ........................................................ local
Debug Mode ...................................................... ENABLEDEs la única comprobación que cuenta: muestra el valor que la aplicación usa de verdad, caché incluida.
La trampa: la configuración en caché
Pones APP_DEBUG=false, recargas y las trazas de error siguen apareciendo. Casi siempre es la caché de configuración.
Cuando se ha ejecutado php artisan config:cache, Laravel escribe todos los valores resueltos en bootstrap/cache/config.php y deja por completo de leer el fichero .env. El comportamiento está medido:
| Paso | config('app.debug') | env('APP_DEBUG') |
|---|---|---|
APP_DEBUG=true, sin caché | true | true |
tras config:cache y cambio a false en el .env | true | NULL |
tras config:clear | false | false |
Dos lecciones. La primera: después de cualquier cambio en el .env en un servidor donde la configuración está en caché, hay que regenerarla.
php artisan config:clear
# o, en producción, regenerar directamente la caché
php artisan config:cacheEs la consecuencia menos conocida, y no afecta solo a la depuración. Una llamada a env('MA_CLE') fuera de un fichero de config/ devolverá null en cuanto haya pasado config:cache. La regla es estricta: env() únicamente en config/, y en cualquier otro sitio config('fichier.cle').
Qué contiene config/app.php
La clave de configuración se limita a leer la variable de entorno, con false como valor de reserva:
'debug' => (bool) env('APP_DEBUG', false),No toques esa línea. Está escrita para que el comportamiento por defecto sea seguro: si APP_DEBUG no aparece en el .env, el modo depuración se queda desactivado. Comprobado borrando la variable: config('app.debug') devuelve efectivamente false.
Poner el valor a fuego en config/app.php tiene dos inconvenientes: el fichero está versionado, así que el ajuste se va a todos los entornos, y el .env pasa a ser engañoso.
Los valores aceptados siguen las reglas de conversión de Laravel, medidas línea a línea:
En el .env | config('app.debug') |
|---|---|
APP_DEBUG=true o (true) o 1 | true |
APP_DEBUG=false o 0 | false |
APP_DEBUG=yes | true |
| variable ausente | false |
yes vale true porque la cadena no se reconoce como booleano y acaba casteada. Es una buena razón para ceñirse a true y false.
Por qué false en producción no se negocia
Con APP_DEBUG=true, la página de error muestra la traza de llamadas, extractos del código fuente y el contenido de las variables de entorno cargadas. Un visitante que provoque un error puede leer, por tanto, tus credenciales de base de datos, tus claves de API y la clave APP_KEY que cifra las sesiones.
Ni siquiera hay que buscar: basta con una URL que provoque una excepción. Es la razón por la que aparecen aplicaciones Laravel comprometidas sin ningún fallo aplicativo concreto.
La configuración correcta de un servidor de producción, como el que se monta en la instalación de Laravel en Debian, cabe en tres líneas:
APP_ENV=production
APP_DEBUG=false
APP_URL=https://exemple.comDespués, una vez desplegado:
php artisan config:cache
php artisan about --only=environment # comprobación: Debug Mode debe mostrar OFFEl mismo razonamiento vale para los formularios públicos, que conviene proteger contra los envíos automatizados antes de abrirlos al público.
Los errores se siguen pudiendo consultar, pero en los logs y no en el navegador:
tail -f storage/logs/laravel.logEsa ruta se construye con storage_path(), descrito en las rutas de la aplicación.
Errores frecuentes
config:cache, Laravel ya no lee el fichero .env. Cualquier cambio exige config:clear o regenerar la caché.env() devuelve NULL en cualquier otro sitio. Usa config('fichier.cle').
