# Gérer les variables d'environnement

Les variables d’environnement passent des réglages à ton build : l’adresse d’une API, un identifiant public, une clé de service. Ce guide les ajoute, les rend sensibles si besoin, et les applique à ton site.

**Résultat attendu** : une variable visible dans l’onglet **Variables d’environnement** du projet, utilisée par le prochain build de l’environnement visé.

**Avant de commencer** : être membre de l’organisation. Modifier une variable demande le rôle membre ou plus.

## Ajouter une variable

1. **Ouvre Ajouter**

   Dans l’onglet **Variables d’environnement** du projet, clique **Ajouter**.

2. **Remplis le nom et la valeur**

   Le nom ne contient que des lettres, des chiffres et `_`, et ne commence pas par un chiffre. Il fait 256 caractères au plus. Les noms qui commencent par `VERCEL_` ou `AGENTHOST_` sont réservés à la plateforme.

   La valeur fait 64 Ko au plus. Une note facultative rappelle à quoi sert la variable : 500 caractères au plus.

3. **Choisis les environnements**

   Chaque variable vise un ou plusieurs environnements :

   | Environnement     | Utilisé par                                                              |
   | ----------------- | ------------------------------------------------------------------------ |
   | **Production**    | Les builds de production, avec `vercel build --prod`                     |
   | **Preview**       | Les builds de preview, donc toutes les branches autres que la production |
   | **Développement** | `vercel pull` depuis ton poste                                           |

   Un même nom peut exister une fois par environnement, avec une valeur différente. Par exemple, `API_URL` pointe vers l’API de production en production, et vers l’API de test en preview.

4. **Ou colle un fichier .env**

   Colle le contenu d’un fichier `.env` dans le champ du nom : chaque ligne devient une variable.

   ```text
   PUBLIC_API_URL=https://api.exemple.ch
   PUBLIC_ANALYTICS_ID=abc123
   ```

   **Vérification** : chaque variable apparaît dans la liste, avec ses environnements.

## Marquer une variable comme sensible

Une clé secrète ou un mot de passe se déclare **sensible**. Une variable sensible :

- ne s’affiche plus jamais après l’enregistrement, ni dans la console ni dans la CLI. Tu peux seulement la remplacer ;
- vise la production ou la preview, jamais le développement ;
- n’est livrée qu’au build du dépôt GitHub, par la clé limitée au projet que pose l’app GitHub. Un `vercel pull` depuis ton poste ne la télécharge pas.

Pour une valeur sensible utilisée par un build hors GitHub, voir [GitHub Actions sans l’application](/docs/guides/github-actions-sans-application/#variables-sensibles).

> **Attention**
>
> Tout ce que le build écrit dans les fichiers du site est public. Une variable lue dans le navigateur, comme celles qui commencent par `PUBLIC_`, `VITE_` ou `NEXT_PUBLIC_`, ne doit jamais contenir un secret, sensible ou non.

## Appliquer un changement

Une variable est lue au build. Les déploiements déjà en ligne gardent les valeurs de leur propre build, et une modification ne les touche pas.

- Pour un projet relié à GitHub, clique **Redéployer la production** pour relancer le build avec les valeurs actuelles.
- Pour un projet déployé avec la CLI, relance le déploiement de production depuis ton dossier ou ta CI :

```bash
vercel --api https://api.host.hgdc.ch pull --environment=production
vercel --api https://api.host.hgdc.ch build --prod
vercel --api https://api.host.hgdc.ch deploy --prebuilt --prod
```

L’onglet signale une variable modifiée depuis le dernier build de production.

**Vérification** : le nouveau déploiement de production affiche la nouvelle valeur. Le déploiement précédent ne la montre pas.

## Récupérer les variables sur ton poste

```bash
vercel --api https://api.host.hgdc.ch pull
```

Par défaut, la commande télécharge l’environnement **Développement** dans `.vercel/.env.development.local`. Ajoute `--environment=preview` ou `--environment=production` pour un autre environnement. Le dossier `.vercel` est ajouté au `.gitignore` : ne le commite pas.

## Si ça ne marche pas

- Une variable sensible n’apparaît pas dans `vercel pull` : c’est voulu. Utilise une valeur de développement, dans une variable non sensible visant l’environnement Développement.
- Le site n’a pas changé après la modification : le déploiement n’a pas été relancé. Voir [Appliquer un changement](#appliquer-un-changement).
- La variable ne peut pas être créée : son nom est réservé, ou sa valeur dépasse 64 Ko. Voir [Variables : référence](/docs/reference/variables/).

## Voir aussi

- [Secrets et coffre](/docs/concepts/secrets-et-coffre/) : comment les valeurs sont chiffrées et qui peut les lire.
- [Synchroniser depuis Doppler](/docs/guides/synchroniser-doppler/) : garder les secrets dans Doppler.