Comment Next.js charge les fichiers .env, dans quel ordre, ce que fait réellement NEXT_PUBLIC_ au moment du build et comment lire les valeurs à l'exécution. Collez votre .env pour voir ce qui atteint le navigateur.
Next.js lit les fichiers .env à la racine du projet et les place dans process.env. Les variables sont réservées au serveur par défaut. Préfixez un nom par NEXT_PUBLIC_ et Next.js copie sa valeur dans le JavaScript du navigateur pendant next build : elle devient publique et figée jusqu'au prochain build. Ne mettez jamais un secret derrière ce préfixe.
Ordre de chargement : le premier fichier qui définit une variable l'emporte
Ordre
Source
Remarques
Les valeurs déjà définies par le shell ou l'hébergeur l'emportent toujours
.env.$(NODE_ENV).local
Par exemple .env.development.local
.env.local
Ignoré quand NODE_ENV vaut test
.env.$(NODE_ENV)
Par exemple .env.production
.env
Valeurs par défaut communes à tous les environnements
Collez ci-dessous le contenu d'un fichier .env. Le vérificateur classe chaque variable en réservée au serveur ou envoyée au navigateur, et signale les noms publics qui ressemblent à des secrets. Tout s'exécute sur cette page ; rien de ce que vous collez n'est envoyé.
Collez vos lignes .env dans la zone, ou modifiez l'exemple.
Lisez le tableau : chaque variable est marquée réservée au serveur ou envoyée au navigateur.
Traitez chaque avertissement, par exemple un nom NEXT_PUBLIC_ contenant KEY, SECRET ou TOKEN.
Relancez un build après avoir modifié une valeur NEXT_PUBLIC_, car l'ancienne valeur est intégrée dans le bundle.
Gardez les fichiers .env à la racine du projet, même si votre code se trouve dans un dossier src. Next.js ne les cherche pas dans src.
Commitez .env et .env.test avec des valeurs par défaut sans risque si votre équipe le souhaite, mais ne commitez jamais les fichiers .env*.local.
Lisez les variables publiques par leur nom littéral complet. process.env[name] ou un process.env déstructuré n'est pas remplacé au build.
Besoin d'une seule image Docker pour la préproduction et la production ? Lisez les variables serveur pendant le rendu dynamique et transmettez en props tout ce dont le navigateur a besoin.
Utilisez loadEnvConfig de @next/env pour charger les mêmes fichiers dans une config d'ORM, un script ou une configuration de tests en dehors de Next.js.
Questions fréquentes
Pourquoi ma variable d'environnement vaut-elle undefined dans le navigateur ?
Sans le préfixe NEXT_PUBLIC_, une variable n'existe que sur le serveur, et Next.js la remplace par une chaîne vide dans le code client. Ajoutez le préfixe uniquement si la valeur peut être publiée sans risque, puis relancez le build.
J'ai modifié une valeur NEXT_PUBLIC_ chez mon hébergeur et rien ne s'est passé. Pourquoi ?
Les valeurs publiques sont intégrées quand next build s'exécute. Un bundle déployé garde l'ancienne valeur jusqu'à un nouveau build avec la nouvelle.
.env.local fonctionne-t-il dans les tests ?
Non. Quand NODE_ENV vaut test, Next.js ignore .env.local pour que chaque exécution de tests reçoive les mêmes valeurs. Placez les valeurs par défaut des tests dans .env.test et vos surcharges personnelles dans .env.test.local.
Une variable peut-elle en référencer une autre ?
Oui. Écrivez $OTHER_NAME dans une valeur et Next.js la développe. Si la valeur doit contenir un signe dollar littéral, échappez-le avec \$.
Quelle est la valeur de NODE_ENV ?
Si vous ne la définissez pas, next dev utilise development et les autres commandes utilisent production. Les valeurs autorisées sont production, development et test.
Ce que fait réellement NEXT_PUBLIC_
Le préfixe est une instruction pour le bundler. Pendant next build, chaque process.env.NEXT_PUBLIC_SOMETHING littéral de votre code est remplacé par la valeur de l'environnement où le build s'est exécuté, et ce texte se retrouve dans les fichiers JavaScript que n'importe qui peut télécharger.
Cela a deux conséquences. D'abord, une variable publique n'est jamais secrète, quel que soit le nom du fichier. Ensuite, elle est figée : promouvoir un build de la préproduction vers la production emporte la valeur de préproduction avec lui.
Lire les valeurs à l'exécution
Le code serveur peut lire n'importe quelle variable, publique ou non. Pour qu'une valeur soit lue à chaque requête plutôt qu'au build, rendez la page dynamiquement, par exemple en attendant connection() de next/server avant de lire process.env.
Le navigateur ne peut pas du tout lire les variables serveur. Si un Client Component a besoin d'une valeur à l'exécution, récupérez-la depuis votre propre Route Handler ou transmettez-la en prop depuis un Server Component.
Se prémunir contre les fuites
Un utilitaire qui lit une clé d'API peut être importé par erreur dans un Client Component. Ajoutez import 'server-only' en haut de ces fichiers et le build échouera si un fichier client les importe.
Lire les variables dans le code
Valeur réservée au serveur dans un Route Handler
DB_URL n'a pas de préfixe, elle n'existe donc que sur le serveur. Les Route Handlers et les Server Components peuvent la lire librement.
Valeur publique dans un Client Component
Le nom littéral complet est obligatoire. Au build, Next.js le remplace par la valeur, et le navigateur voit une simple chaîne.
Lire une valeur à chaque requête
Attendre connection() force le rendu dynamique de la page, si bien que la valeur vient du serveur en cours d'exécution plutôt que du build.
loadEnvConfig applique le même ordre de chargement, ce qui garde les scripts et les configurations de tests alignés sur l'app.
Vérificateur de .env
Collez vos lignes .env
Où chaque variable peut être lue
Variable
Disponible dans
Remarque
Serveur uniquement
Serveur et navigateur (intégrée au build)
Ce n'est pas une ligne de variable
Ce nom ressemble à un secret. Tout ce qui porte NEXT_PUBLIC_ est visible par chaque visiteur.
Référence {v}, que Next.js développe.
NODE_ENV n'accepte que production, development ou test.
Aucune variable trouvée pour l'instant.
{n} réservées au serveur, {v} envoyées au navigateur