Après un déploiement, env() renvoie null ou une route répond 404 : les caches de Laravel

Le code fonctionne en local, le déploiement s'est bien passé, et pourtant en production une clé d'API arrive vide parce que env('MA_CLE') renvoie null, ou une page que vous venez d'ajouter répond 404 alors que sa route est bien dans routes/web.php. Dans les deux cas, la cause est la même : les caches que Laravel construit au déploiement, celui de la configuration et celui des routes. La bonne réponse n'est pas de les désactiver, mais d'écrire le code pour qu'il fonctionne avec eux, et de les reconstruire au bon moment.

Pourquoi env() renvoie null après config:cache ?

php artisan config:cache regroupe tous les fichiers de config/ dans un seul fichier, bootstrap/cache/config.php. Une fois ce cache en place, la documentation de Laravel est claire : le fichier .env n'est plus chargé, ni pendant les requêtes ni pendant les commandes Artisan. env() ne renvoie alors que les variables d'environnement définies au niveau du système, et null pour celles qui ne sont que dans .env.

Nous l'avons reproduit sur une application neuve, avec PILOT_VAR=bonjour dans .env, ce fichier de configuration et une route de test :

// config/pilot.php
return [
    'var' => env('PILOT_VAR'),
];

// routes/web.php
Route::get('/pilot-env', function () {
    return response()->json([
        'env' => env('PILOT_VAR'),
        'config' => config('pilot.var'),
        'external' => env('EXT_VAR'),
    ]);
});

EXT_VAR est une variable définie au lancement du serveur PHP, pas dans .env. Résultat :

La valeur n'a pas disparu : elle a été lue au moment du config:cache et figée dans la configuration. C'est env() appelé en dehors de config/ qui ne la trouve plus.

Comment corriger : env() dans config/, config() partout ailleurs

La règle de la documentation tient en une ligne : n'appeler env() que dans les fichiers de config/, et lire les valeurs avec config() partout ailleurs (contrôleurs, services, jobs, vues). Pour une clé d'API :

// config/services.php
'meteo' => [
    'key' => env('METEO_API_KEY'),
],

// Partout ailleurs dans l'application
$key = config('services.meteo.key');

Après config:cache, env('METEO_API_KEY') renvoie null et config('services.meteo.key') renvoie bien la clé.

L'ancien réflexe, lancer php artisan config:clear pour "réparer", supprime le fichier de cache : env() refonctionne, mais l'application perd le cache et le problème revient au déploiement suivant. La documentation recommande au contraire de lancer config:cache à chaque déploiement en production, et de ne pas le faire en développement local.

Pourquoi une nouvelle route répond 404 après un déploiement ?

php artisan route:cache enregistre toutes les routes dans bootstrap/cache/routes-v7.php, et c'est ce fichier qui est chargé à chaque requête. Une route ajoutée après sa création reste inconnue tant qu'il n'est pas reconstruit ou supprimé : c'est le cas d'un déploiement qui copie le nouveau code sans relancer route:cache.

Dans notre test, une route /nouvelle-page ajoutée après route:cache répond 404, et php artisan route:list --path=nouvelle ne la trouve pas. Après php artisan route:clear, elle répond 200. Après un nouveau php artisan route:cache, elle répond toujours 200, puisqu'elle fait désormais partie du cache.

cache:clear vide-t-il le cache des routes ?

Non. php artisan cache:clear vide le cache applicatif, celui que vous remplissez avec Cache::put() ou Cache::remember(). Il ne touche ni à bootstrap/cache/config.php ni à bootstrap/cache/routes-v7.php : après un cache:clear, notre route restait en 404 et env() renvoyait toujours null.

Pour savoir où en est un serveur, php artisan about --only=cache affiche CACHED ou NOT CACHED pour la configuration, les événements, les routes et les vues.

Dans quel ordre lancer les commandes au déploiement ?

php artisan optimize enchaîne config:cache, event:cache, route:cache et view:cache. Il doit passer une fois le nouveau code et le .env définitif en place, sinon il fige l'état précédent. Voici la séquence que nous avons exécutée de bout en bout :

# Une fois le nouveau code récupéré (git pull ou équivalent)
composer install --no-dev --optimize-autoloader
php artisan migrate --force
php artisan optimize
php artisan reload

php artisan reload relance les services qui tournent en continu (dans notre test, les workers de file d'attente et le planificateur) pour qu'ils utilisent le nouveau code. Si l'application affiche des fichiers envoyés par ses utilisateurs, vérifiez aussi le lien public/storage. En cas de doute sur un serveur, php artisan optimize:clear repart de zéro et php artisan optimize reconstruit tout ; gardez en tête que optimize:clear vide aussi le cache applicatif.

Ce sont des réglages que nous mettons en place sur les applications que nous hébergeons et maintenons, comme sur les applications sur mesure que nous développons. Un déploiement qui casse en production ? Parlons-en.

Testé avec Laravel 13.37.0 et PHP 8.3.6.

Questions fréquentes