Variables d'environnement

Environment variables hold the configuration and secrets your app needs at build time and at runtime, such as API keys, database URLs and feature flags, without any of it living in your repository…

Les variables d'environnement contiennent la configuration et les secrets dont votre application a besoin au moment de la compilation et à l'exécution, comme les clés API, les URL de base de données et les indicateurs de fonctionnalité, sans qu'aucun élément de ceux-ci ne se trouve dans votre référentiel. Ce guide couvre l'endroit où ils se trouvent dans Orbit, comment fonctionnent la portée et la priorité, le marquage d'une valeur comme secrète, l'importation et l'exportation en masse, et les erreurs qui produisent une variable qui est d'une façon ou d'une autre toujours indéfinie.

Où ils se trouvent

Ouvrez votre projet dans Orbit et cliquez sur l'onglet Env vars, à /orbit/<project-id>/env-vars.

La page est organisée en sections:

All environments en haut: variables à l'échelle du projet, disponibles dans chaque compilation.
Une section réductible par environnement (Production, Staging, et tout aperçu) contenant les remplacements de cet environnement.

Au-dessus de la liste se trouve une boîte de recherche et un filtre Secrets only, qui sont le moyen rapide de naviguer dans une longue liste.

Comment fonctionne la portée

Portée	Ce qu'il affecte
All environments (à l'échelle du projet)	Injecté dans chaque compilation de ce projet
Environment-level override	S'applique uniquement à cet environnement, et prime sur la valeur à l'échelle du projet ayant la même clé

Le sous-titre de la page énonce clairement la règle: les variables à l'échelle du projet sont disponibles dans chaque compilation, et les remplacements au niveau de l'environnement ont la priorité.

Une configuration typique est une variable à l'échelle du projet DATABASE_URL pointant vers une base de données de test, avec un remplacement au niveau de la production pointant vers la vraie. Les compilations de production obtiennent la véritable base de données, tout le reste obtient la base de test, et rien que vous n'ajoutiez accidentellement ne fuit les identifiants de production dans un aperçu.

Il existe aussi un contrôle Available in sur les variables à l'échelle du projet, vous permettant d'exclure les types d'environnement particuliers (production, staging, preview) d'une variable qui est autrement à l'échelle du projet.

Des détails complets sur la portée par environnement, y compris le raisonnement de sécurité, se trouvent dans Définition des variables d'environnement par environnement.

Une variable à l'échelle du projet est injectée dans les compilations d'aperçu de branche, et les URL d'aperçu sont accessibles au public par quiconque a le lien. Les identifiants de base de données de production, les clés de paiement actives et les jetons d'administrateur doivent être limités à la production uniquement. C'est la chose la plus importante à bien faire sur cette page.

Ajouter une variable

Faites défiler jusqu'au formulaire Add variable au bas de l'onglet Env vars.
Entrez la KEY, par exemple NEXT_PUBLIC_API_URL.
Entrez la value.
Choisissez une Scope: All environments (project-wide), ou un remplacement d'environnement spécifique.
Si vous avez choisi l'échelle du projet, utilisez les boutons Available in pour désélectionner les types d'environnement auxquels cette variable ne devrait pas accéder.
Cochez Mark as secret pour tout ce qui est sensible.
Cliquez sur Add.

Le formulaire vous indique ce qu'il est sur le point de faire avant de vous engager: un remplacement d'environnement affiche un avis indiquant qu'il s'appliquera uniquement aux compilations de cet environnement, et une variable à l'échelle du projet restreinte affiche les types d'environnement dans lesquels elle sera injectée.

Quand les modifications prennent effet

L'ajout, la modification ou la suppression d'une variable ne modifie pas le déploiement actuellement actif. Les variables sont injectées lors de l'exécution d'une compilation, donc la modification s'applique à partir du prochain déploiement. Redéployez après avoir modifié quoi que ce soit sur lequel votre application dépend.

Orbit est explicite à ce sujet. Ouvrez la page de détails d'un déploiement et, si la configuration a changé depuis sa compilation, vous obtenez un avis Environment variables updated since this deployment vous indiquant que la modification ne prendra pas effet tant que vous ne redéployez.

Secrets

Cochez Mark as secret pour tout ce que vous ne colleriez pas dans un chat: clés API, mots de passe de base de données, jetons, clés de signature.

Les valeurs secrètes sont masquées dans le panneau et portent un badge secret. Les valeurs non-secrètes affichent un marqueur (plain).

La valeur d'un secret ne peut pas être relue après sa sauvegarde, ni par vous ni par quiconque d'autre dans le panneau. Vous pouvez la remplacer (cliquez sur l'icône d'édition, tapez une nouvelle valeur, enregistrez) mais vous ne pouvez pas la révéler. Gardez votre propre copie dans un gestionnaire de mots de passe avant de la sauvegarder ici.

Orbit suit aussi depuis combien de temps une valeur est en place et affiche un badge d'âge sur les variables plus anciennes, avec un conseil suggérant une rotation. C'est un coup de pouce, pas une application.

Édition et suppression

Cliquez sur l'icône d'édition à côté d'une variable pour modifier sa valeur. Cliquez sur Delete pour la supprimer, et confirmez: le dialogue vous avertit que les compilations qui en dépendent se briseront, ce qui est la description exacte de ce qui se passe au prochain déploiement.

Importation et exportation en masse

Deux boutons en haut de l'onglet gèrent le travail en masse.

Import .env ouvre une boîte de collage. Collez le contenu d'un fichier .env, choisissez une portée, et Orbit vous indique combien de variables il a détectées et combien il marquera comme secrètes. Il signale automatiquement les clés en fonction de leurs noms, donc tout ce qui contient SECRET, TOKEN, KEY, PASSWORD et similaire est marqué secret avant l'importation. Il y a une option Overwrite existing variables with the same key, désactivée par défaut.

Download .env produit un modèle contenant les noms de variables uniquement, sans valeurs. Il est destiné à être partagé avec un coéquipier qui remplit alors ses propres valeurs, non pas utilisé comme sauvegarde.

Le téléchargement d'un modèle .env n'inclut jamais les valeurs, y compris pour les variables non-secrètes. Il n'y a aucun moyen d'exporter les valeurs d'Orbit. Si vous avez besoin d'une copie d'une valeur, prenez-la d'où vous l'avez originellement générée.

Copie de variables entre environnements

Le panneau Copy variables between environments copie un ensemble complet d'une portée à une autre. Choisissez un From (niveau du projet ou un environnement spécifique) et un To, cochez optionnellement Overwrite variables that already exist in the target, et cliquez sur Preview pour voir exactement combien seront ajoutés, mis à jour et ignorés avant de vous engager.

Il existe également une page Env sync check qui compare la production et le staging clé par clé et signale ce qui ne se trouve que dans l'une, ce qui diffère, et ce qui correspond. C'est l'outil approprié pour "pourquoi le staging fonctionne et la production ne fonctionne pas".

Partage de variables entre projets

Si plusieurs projets ont besoin des mêmes identifiants, utilisez un env group plutôt que de le copier dans chaque projet. Allez à Orbit, puis Env groups, créez un groupe, ajoutez des variables à celui-ci, et liez les projets qui en ont besoin.

Les variables de groupe sont injectées au moment de la compilation, et les variables au niveau du projet et au niveau de l'environnement ont la priorité sur les variables de groupe. Vous pouvez avoir jusqu'à 20 groupes sur un compte.

Notes sur le framework

Les variables qui atteignent le navigateur sont décidées par votre framework, non par Orbit. Orbit injecte tout ce qui est en portée; le framework décide ce qu'il faut exposer.

Next.js: les clés préfixées NEXT_PUBLIC_ sont incorporées dans le bundle du navigateur au moment de la compilation. Tout le reste reste côté serveur.
Vite: les clés préfixées VITE_ sont exposées au navigateur. Tout le reste est compilation uniquement.
Node.js apps: tout ce qui est en portée est sur process.env pendant la compilation, et à l'exécution quand Server mode est activé.

Ne marquez jamais une valeur comme secrète et ne la préfixez pas aussi NEXT_PUBLIC_ ou VITE_. Le flag secret contrôle uniquement si le panneau vous affiche la valeur; le préfixe contrôle si votre framework l'expédie au navigateur de chaque visiteur. Le préfixe gagne.

Vérification de ce qu'une compilation a réellement reçu

Chaque page de détails de déploiement énumère les keys des variables d'environnement qui ont été injectées au moment de la compilation, et les différencie par rapport à votre configuration actuelle: ajoutées, modifiées, supprimées et inchangées. Les clés turquoise provenaient d'un remplacement spécifique à l'environnement, les grises du niveau du projet. Les valeurs ne sont jamais stockées ou affichées, mais en survolant une clé, vous obtenez une empreinte digitale SHA-256, ce qui suffit pour confirmer que deux environnements contiennent la même valeur sans la révéler.

C'est la réponse définitive à "ma variable atteint-elle réellement la compilation". Vérifiez-la avant de modifier autre chose.

Dépannage

La variable est indéfinie à l'exécution. Vérifiez que le déploiement est postérieur au changement, puis vérifiez que la portée couvre cet environnement, puis vérifiez les règles de préfixe du framework ci-dessus. Dans cet ordre.

Cela fonctionne en production mais pas dans un aperçu. La variable a une portée production uniquement, ou une variable à l'échelle du projet a preview désélectionné sous Available in. C'est généralement intentionnel.

Cela fonctionne localement mais pas dans la compilation. Votre fichier .env local ne se trouve pas dans le référentiel, et ne devrait pas s'y trouver. Importez-le avec Import .env et choisissez la bonne portée.

Staging n'a tout ce que la production a. Activez Inherit production env vars dans Settings, sous Staging: environment variables, ou utilisez Copy variables between environments.