Den Debug-Modus stellst du über APP_DEBUG in der Datei .env ein: true lokal, false in der Produktion, ausnahmslos. Den tatsächlichen Zustand prüfst du mit php artisan about --only=environment. Greift die Änderung nicht, liegt die Konfiguration im Cache: php artisan config:clear.
Der Debug-Modus entscheidet, was ein Besucher zu sehen bekommt, wenn deine Anwendung abstürzt: den vollständigen Stacktrace mit Quellcode und Umgebungsvariablen oder eine neutrale Fehlerseite. Es ist eine Einstellung von einer einzigen Zeile und zugleich eines der häufigsten Datenlecks in der Produktion.
Artikel aus dem Lernpfad Webentwicklung. Geprüft mit Laravel 13.30.1 und PHP 8.4.25.
Aktivieren und deaktivieren
Eingestellt wird das in der Datei .env im Projektstamm, und sonst nirgends:
APP_ENV=local
APP_DEBUG=trueZum Abschalten setzt du den Wert auf false:
APP_ENV=production
APP_DEBUG=falseDen tatsächlichen Zustand prüfst du, ohne eine einzige Zeile Code zu schreiben:
php artisan about --only=environment Environment ........................................................ local
Debug Mode ...................................................... ENABLEDDas ist die einzige Prüfung, die zählt: Sie zeigt den Wert, den die Anwendung wirklich verwendet, Cache inbegriffen.
Die Falle: die Konfiguration im Cache
Du setzt APP_DEBUG=false, lädst neu, und die Stacktraces erscheinen weiterhin. Fast immer ist der Konfigurations-Cache schuld.
Sobald php artisan config:cache gelaufen ist, schreibt Laravel alle aufgelösten Werte nach bootstrap/cache/config.php und liest die Datei .env überhaupt nicht mehr. Das Verhalten wurde gemessen:
| Schritt | config('app.debug') | env('APP_DEBUG') |
|---|---|---|
APP_DEBUG=true, ohne Cache | true | true |
nach config:cache, dann Wechsel auf false in der .env | true | NULL |
nach config:clear | false | false |
Zwei Lehren daraus. Erstens: Nach jeder Änderung an der .env auf einem Server mit gecachter Konfiguration muss der Cache neu aufgebaut werden.
php artisan config:clear
# oder in der Produktion den Cache direkt neu aufbauen
php artisan config:cacheDas ist die am wenigsten bekannte Folge, und sie betrifft nicht nur den Debug-Modus. Ein Aufruf von env('MA_CLE') außerhalb einer Datei in config/ liefert null, sobald config:cache gelaufen ist. Die Regel ist strikt: env() nur in config/, überall sonst config('fichier.cle').
Was in config/app.php steht
Der Konfigurationsschlüssel liest lediglich die Umgebungsvariable aus, mit false als Rückfallwert:
'debug' => (bool) env('APP_DEBUG', false),Ändere diese Zeile nicht. Sie ist so geschrieben, dass das Standardverhalten sicher ist: Fehlt APP_DEBUG in der .env, bleibt der Debug-Modus aus. Nachgeprüft durch Löschen der Variablen, config('app.debug') liefert dann tatsächlich false.
Den Wert fest in config/app.php zu schreiben, hat zwei Nachteile: Die Datei liegt in der Versionsverwaltung, die Einstellung wandert also in alle Umgebungen, und die .env wird irreführend.
Die akzeptierten Werte folgen den Umwandlungsregeln von Laravel, hier Zeile für Zeile gemessen:
In der .env | config('app.debug') |
|---|---|
APP_DEBUG=true oder (true) oder 1 | true |
APP_DEBUG=false oder 0 | false |
APP_DEBUG=yes | true |
| Variable fehlt | false |
yes ergibt true, weil der String nicht als Boolean erkannt und deshalb gecastet wird. Ein guter Grund, bei true und false zu bleiben.
Warum false in der Produktion nicht verhandelbar ist
Mit APP_DEBUG=true zeigt die Fehlerseite den Stacktrace, Ausschnitte aus dem Quellcode und den Inhalt der geladenen Umgebungsvariablen. Ein Besucher, der einen Fehler auslöst, kann damit deine Datenbank-Zugangsdaten, deine API-Schlüssel und den Schlüssel APP_KEY lesen, mit dem die Sessions verschlüsselt werden.
Suchen muss dafür niemand: Eine URL, die eine Exception auslöst, genügt. Aus diesem Grund werden Laravel-Anwendungen kompromittiert, ohne dass eine besondere Lücke im Code steckt.
Die richtige Konfiguration eines Produktionsservers, wie er in der Laravel-Installation auf Debian aufgesetzt wird, passt in drei Zeilen:
APP_ENV=production
APP_DEBUG=false
APP_URL=https://exemple.comUnd nach dem Deployment:
php artisan config:cache
php artisan about --only=environment # Kontrolle: Debug Mode muss OFF anzeigenDieselbe Überlegung gilt für öffentliche Formulare, die du vor der Freigabe gegen automatisierte Einsendungen absichern solltest.
Die Fehler bleiben einsehbar, nur im Log statt im Browser:
tail -f storage/logs/laravel.logDieser Pfad entsteht über storage_path(), beschrieben unter den Pfaden der Anwendung.
Häufige Fehler
config:cache liest Laravel die Datei .env nicht mehr. Jede Änderung verlangt config:clear oder einen neu aufgebauten Cache.env() überall sonst NULL. Nimm config('fichier.cle').
