Vercel : variables d’environnement sans .env dans Git

Ce guide s’adresse à un projet déjà hébergé sur Vercel. Vous devez pouvoir accéder à ses paramètres et savoir quelles variables l’application lit. L’exemple ci-dessous concerne Next.js ; les noms de variables d’un autre framework ne peuvent pas être repris automatiquement. Ce guide s’appuie sur la documentation officielle ; il n’a pas été testé sur un compte réel.

La documentation fournit des informations pratiques sur l’utilisation d’Ailoot.

Pourquoi vous n’avez pas besoin d’ajouter .env à Git ?#

Une variable d’environnement est un paramètre composé d’un nom et d’une valeur que l’application reçoit séparément de son code source. Par exemple, le nom SERVICE_API_KEY permet au programme d’accéder à la valeur de la clé d’un service externe. Ne placez pas la clé elle-même dans le guide, dans votre conversation avec un agent ou dans le dépôt.

Next.js peut charger des variables depuis des fichiers .env* locaux. Toutefois, un fichier local et les paramètres d’un projet dans Vercel sont deux emplacements distincts. Si le fichier n’est pas envoyé dans le dépôt, définissez les valeurs séparément sur la plateforme d’hébergement. Le modèle standard create-next-app ajoute les fichiers .env à .gitignore ; la documentation Next.js avertit qu’il ne faut presque jamais les envoyer dans le dépôt.

Si vous ne savez toujours pas ce qui peut être stocké dans les fichiers source, commencez par le contrôle de sécurité d’un projet créé avec l’IA. Ici, nous abordons une question plus précise : où définir la configuration d’un déploiement Vercel donné.

Déterminez d’abord où l’application lit la variable#

Avant de saisir des valeurs, dressez une liste des noms, sans inclure les secrets eux-mêmes. Pour chaque nom, vous devez établir trois éléments : l’environnement qui l’utilise, l’endroit où s’exécute le code qui lit la variable et le moment où la valeur est nécessaire.

L’environnement Development est destiné au développement local. Preview concerne les déploiements de prévisualisation et Production la version principale publiée. Preview peut avoir des paramètres propres à une branche Git : ils remplacent les paramètres généraux de Preview portant les mêmes noms.

Dans un projet Next.js, les variables sans NEXT_PUBLIC_ sont disponibles sur le serveur par défaut. Le préfixe NEXT_PUBLIC_ permet d’intégrer la valeur au JavaScript transmis au navigateur. Cette option convient à un paramètre explicitement public, comme un libellé de version non secret, mais pas à une clé API privée. Même sans ce préfixe, le code de l’application ne doit pas renvoyer manuellement un secret au client.

Si vous n’avez pas encore identifié le framework, demandez à l’agent de le déterminer à partir des fichiers du projet. La comparaison d’Astro et de Next.js peut vous aider à comprendre les différences ; la règle NEXT_PUBLIC_ ne s’applique pas à toutes les applications React.

La configuration de l’hébergement fait partie des tâches liées au travail sur une application avec un agent IA.

Comment ajouter une variable à un projet Vercel#

Effectuez vous-même les étapes dans le tableau de bord officiel. Ne donnez pas à l’agent une vraie clé pour qu’il remplisse le formulaire et ne joignez pas de capture d’écran où sa valeur apparaît.

1. Ouvrez le tableau de bord Vercel et sélectionnez le bon projet. Ne vous fiez pas uniquement à un nom de dépôt correspondant : vérifiez que vous configurez bien l’application que vous comptez ouvrir.
2. Dans la barre latérale des paramètres du projet, ouvrez Environment Variables.
3. Dans Name, saisissez le nom lu par l’application, par exemple SERVICE_API_KEY. Il s’agit d’un nom donné à titre d’exemple ; si le code en attend un autre, utilisez son orthographe exacte.
4. Dans Value, saisissez la valeur stockée dans votre gestionnaire d’identifiants. Ne l’inscrivez pas dans le code source, une conversation ou un journal de vérification.
5. Sélectionnez l’environnement auquel ce paramètre doit s’appliquer. Utilisez Preview pour vérifier une version de prévisualisation et Production pour la version principale. N’attribuez pas automatiquement un même secret à tous les environnements.
6. Si le paramètre Preview concerne une branche précise, vérifiez la branche sélectionnée et toute substitution portant le même nom.
7. Cliquez sur Save.

Vercel rend les variables du projet disponibles pendant le build et lors de l’exécution des Vercel Functions côté serveur. Toutefois, le fait qu’une valeur soit disponible dans Vercel ne signifie pas qu’elle peut être envoyée au navigateur : cela dépend du code de l’application et des règles du framework.

Pourquoi un nouveau déploiement est nécessaire après l’enregistrement#

L’enregistrement d’une variable ne modifie pas les déploiements existants. La documentation Vercel indique que vous devez redéployer le projet pour que le nouveau paramètre soit appliqué à la version que vous utilisez.

Lorsque vous travaillez avec Git, vous pouvez créer un nouveau déploiement Production en envoyant un commit dans la branche indiquée sous Production Branch, et un déploiement Preview en envoyant un commit dans une autre branche. Ne supposez pas que la branche principale s’appelle toujours main : vérifiez le paramètre de votre projet. Il doit s’agir d’une publication normale du projet, approuvée par les personnes concernées, sans ajouter de fichier contenant un secret au commit.

Après le lancement du déploiement, attendez la fin du build, puis ouvrez l’URL du nouveau déploiement. Notez son URL, son environnement et sa branche. Si vous vérifiez l’ancienne URL d’un déploiement précis, les nouveaux paramètres n’y apparaîtront pas.

Next.js impose une autre condition : les références comme process.env.NEXT_PUBLIC_RELEASE_LABEL sont remplacées par leurs valeurs lors de next build. La valeur est fixée à la fin du build. Modifier le paramètre sans lancer un nouveau build ne réécrira pas le JavaScript côté client déjà transmis.

Comment vérifier le résultat sans exposer la clé#

Commencez par un exemple sûr : un libellé explicitement non secret nommé NEXT_PUBLIC_RELEASE_LABEL et ayant pour valeur preview-check. Ce sont un nom et un texte donnés en exemple, pas une clé ni un test effectué ici. Si une application Next.js lit directement cette variable via process.env.NEXT_PUBLIC_RELEASE_LABEL, elle peut afficher le libellé à l’endroit prévu dans l’interface après un nouveau build. Cette vérification confirme uniquement que le paramètre public a bien été transmis.

Une clé privée se vérifie autrement. N’affichez ni sa valeur, ni une partie de celle-ci, ni sa longueur, ni l’ensemble de process.env. Ne créez pas d’URL publique qui renvoie le contenu de la variable. Vérifiez d’abord uniquement si le paramètre est « présent / absent » sur le serveur, puis vérifiez séparément la fonction de l’application qui utilise le service. La présence d’un paramètre ne prouve ni que la clé est valide ni qu’elle dispose des autorisations nécessaires.

Vous pouvez consigner les résultats sans secrets :

• le projet, l’environnement et la branche correspondent à ceux sélectionnés lors de la configuration ;
• vous vérifiez l’URL d’un nouveau déploiement créé après l’enregistrement de la variable ;
• le build est terminé et la fonction requise de l’application a été exécutée avec des données de test sûres ;
• le secret n’est exposé ni dans le navigateur, ni dans les réponses API, ni dans les journaux ou les conversations.

Si la fonction effectue un paiement, envoie un message ou exécute une autre action ayant des conséquences, utilisez le mode de test prévu par le service. La vérification de la configuration n’autorise pas, à elle seule, une opération réelle.

Que vérifier si la valeur reste undefined#

undefined signifie qu’aucune valeur n’a été obtenue à cet endroit du code. Vérifiez le nom, l’environnement et la version dans cet ordre, sans modifier tous les paramètres à la fois.

Après avoir vérifié le nom, l’environnement et la nouvelle version, une erreur dans la fonction ne prouve toujours pas que la variable en est la cause. Examinez l’erreur précise du code côté serveur sans publier de données de diagnostic contenant des secrets. Ce guide ne promet pas de résoudre toutes les réponses HTTP 500.

Le passage à votre propre serveur nécessite une autre procédure : consultez le guide de déploiement d’un projet avec Coolify. Les noms des boutons et les étapes de configuration de Vercel ne s’y appliquent pas.

Accéder à Ailoot.