Aller au contenu

Utiliser des variables d'environnement

Astro vous donne accès à la prise en charge des variables d’environnement intégrées de Vite et inclut certaines variables d’environnement par défaut pour votre projet qui vous permettent d’accéder aux valeurs de configuration de votre projet actuel (par exemple site, base), que votre projet soit exécuté en mode développement ou production, et plus encore.

Astro fournit également un moyen d’utiliser et d’organiser vos variables d’environnement avec la sûreté du typage. Celui-ci est disponible pour une utilisation dans le contexte Astro (par exemple, les composants Astro, les routes et les points de terminaison, les composants de framework UI, le middleware) et il est géré avec un schéma dans votre configuration Astro.

Support intégré de Vite

Titre de la section Support intégré de Vite

Astro utilise le support intégré de Vite pour les variables d’environnement, qui sont remplacées statiquement au moment de la construction, et vous permet d’utiliser toutes ses méthodes pour travailler avec elles.

Notez que si toutes les variables d’environnement sont disponibles dans le code côté serveur, seules les variables d’environnement préfixées par PUBLIC_ sont disponibles dans le code côté client pour des raisons de sécurité.

.env
SECRET_PASSWORD=password123
PUBLIC_ANYBODY=there

Dans cet exemple, PUBLIC_ANYBODY (accessible via import.meta.env.PUBLIC_ANYBODY) disponible dans le code du serveur ou du client, tandis que SECRET_PASSWORD (accessible via import.meta.env.SECRET_PASSWORD) ne sera disponible que côté serveur.

Autocomplétion pour TypeScript

Titre de la section Autocomplétion pour TypeScript

Par défaut, Astro fournit une définition de type pour import.meta.env dans astro/client.d.ts.

Bien que vous puissiez définir davantage de variables d’environnement personnalisées dans les fichiers .env.[mode], vous souhaiterez peut-être obtenir TypeScript IntelliSense pour les variables d’environnement définies par l’utilisateur qui sont préfixées par PUBLIC_.

Pour y parvenir, vous pouvez créer un env.d.ts dans src/ et configurer ImportMetaEnv comme ceci :

src/env.d.ts
interface ImportMetaEnv {
  readonly DB_PASSWORD: string;
  readonly PUBLIC_POKEAPI: string;
  // plus de variables d'environnement...
}


interface ImportMeta {
  readonly env: ImportMetaEnv;
}

Variables d’environnement par défaut

Titre de la section Variables d’environnement par défaut

Astro inclut quelques variables d’environnement par défaut :

  • import.meta.env.MODE : Le mode dans lequel tourne votre site. C’est development lorsque vous exécutez astro dev et production lorsque vous exécutez astro build.
  • import.meta.env.PROD : true si votre site est exécuté en mode production ; false sinon.
  • import.meta.env.DEV : true si votre site tourne en développement ; false sinon. Toujours l’opposé de import.meta.env.PROD.
  • import.meta.env.BASE_URL : L’URL de base à partir de laquelle votre site est servi. Elle est déterminée par l’option de configuration base.
  • import.meta.env.SITE : C’est l’option site spécifiée dans le fichier astro.config de votre projet.
  • import.meta.env.ASSETS_PREFIX : Le préfixe pour les liens d’actifs générés par Astro si l’option de configuration build.assetsPrefix est définie. Ceci peut être utilisé pour créer des liens d’actifs non gérés par Astro.

Utilisez-les comme n’importe quelle autre variable d’environnement.

const isProd = import.meta.env.PROD;
const isDev = import.meta.env.DEV;

Définir des variables d’environnement

Titre de la section Définir des variables d’environnement

Le fichier .env

Titre de la section Le fichier .env

Les variables d’environnement peuvent être chargées à partir des fichiers .env dans le répertoire de votre projet.

Créez simplement un fichier .env dans le répertoire du projet et ajoutez-y quelques variables.

.env
# Elle sera disponible uniquement pour le code exécuté sur le serveur !
DB_PASSWORD="foobar"
# Elle sera disponible partout !
PUBLIC_POKEAPI="https://pokeapi.co/api/v2"

Vous pouvez également ajouter .production, .development ou un nom de mode personnalisé au nom de fichier lui-même (par exemple env.testing, .env.staging). Cela vous permet d’utiliser différents ensembles de variables d’environnement à différents moments.

Les commandes astro dev et astro build sont par défaut respectivement en modes "development" et "production". Vous pouvez exécuter ces commandes avec l’option --mode pour transmettre une valeur différente pour mode et charger le fichier .env correspondant.

Cela vous permet d’exécuter le serveur de développement ou de créer votre site en vous connectant à différentes API :

Fenêtre du terminal
# Exécute le serveur de développement connecté à une API « staging »
astro dev --mode staging


# Crée un site qui se connecte à une API de « production » avec des informations de débogage supplémentaires
astro build --devOutput


# Crée un site qui se connecte à une API de « test »
astro build --mode testing

Pour plus d’informations sur les fichiers .env, voir la documentation de Vite (EN).

Dans le fichier de configuration Astro

Titre de la section Dans le fichier de configuration Astro

Astro évalue les fichiers de configuration avant de charger vos autres fichiers. Cela signifie que vous ne pouvez pas utiliser import.meta.env dans astro.config.mjs pour accéder aux variables d’environnement qui ont été définies dans les fichiers .env.

Vous pouvez utiliser process.env dans un fichier de configuration pour accéder à d’autres variables d’environnement, comme celles définies par la CLI.

Vous pouvez également utiliser l’assistant loadEnv de Vite pour charger manuellement les fichiers .env.

astro.config.mjs
import { loadEnv } from "vite";
const { SECRET_PASSWORD } = loadEnv(process.env.NODE_ENV, process.cwd(), "");

Utilisation en CLI

Titre de la section Utilisation en CLI

Vous pouvez également ajouter des variables d’environnement lorsque vous exécutez votre projet :

Fenêtre du terminal
PUBLIC_POKEAPI=https://pokeapi.co/api/v2 npm run dev

Obtenir des variables d’environnement

Titre de la section Obtenir des variables d’environnement

Les variables d’environnement dans Astro sont accessibles avec import.meta.env, en utilisant la fonctionnalité import.meta ajoutée dans ES2020, au lieu de process.env.

Par exemple, utilisez import.meta.env.PUBLIC_POKEAPI pour obtenir la variable d’environnement PUBLIC_POKEAPI.

// Quand import.meta.env.SSR === true
const data = await db(import.meta.env.DB_PASSWORD);


// Quand import.meta.env.SSR === false
const data = fetch(`${import.meta.env.PUBLIC_POKEAPI}/pokemon/squirtle`);

Lorsque vous utilisez SSR, les variables d’environnement peuvent être accédées au moment de l’exécution en fonction de l’adaptateur SSR utilisé. Avec la plupart des adaptateurs, vous pouvez accéder aux variables d’environnement avec process.env, mais certains adaptateurs fonctionnent différemment. Pour l’adaptateur Deno, vous utiliserez Deno.env.get(). Voir comment accéder au runtime Cloudflare pour gérer les variables d’environnement lors de l’utilisation de l’adaptateur Cloudflare. Astro vérifiera d’abord l’environnement du serveur pour les variables, et si elles n’existent pas, Astro les cherchera dans les fichiers .env.

Variables d’environnement avec sûreté du typage

Titre de la section Variables d’environnement avec sûreté du typage

L’API astro:env vous permet de configurer un schéma avec sûreté du typage pour les variables d’environnement que vous avez définies. Cela vous permet d’indiquer s’ils doivent être disponibles sur le serveur ou le client, et de définir leur type de données et leurs propriétés supplémentaires.

Vous développez un adaptateur ? Découvrez comment rendre un adaptateur compatible avec astro:env.

Utilisation de base

Titre de la section Utilisation de base

Définissez votre schéma

Titre de la section Définissez votre schéma

Pour configurer un schéma, ajoutez l’option env.schema à votre configuration Astro :

astro.config.mjs
import { defineConfig } from 'astro/config'


export default defineConfig({
  env: {
    schema: {
      // ...
    }
  }
})

Vous pouvez ensuite enregistrer des variables sous forme de chaîne de caractères, de nombre, d’énumération ou de booléen en utilisant l’assistant envField. Définissez le type de variable d’environnement Définissez le type de variable d’environnement en fournissant les propriétés context (client ou serveur) et access (secret ou public) pour chaque variable, et transmettez toutes les propriétés supplémentaires telles que optional ou default dans un objet :

astro.config.mjs
import { defineConfig, envField } from 'astro/config'


export default defineConfig({
  env: {
    schema: {
      API_URL: envField.string({ context: "client", access: "public", optional: true }),
      PORT: envField.number({ context: "server", access: "public", default: 4321 }),
      API_SECRET: envField.string({ context: "server", access: "secret" }),
    }
  }
})

Les types seront générés pour vous lors de l’exécution de astro dev ou astro build, mais vous pouvez exécuter astro sync pour générer des types uniquement.

Utiliser les variables de votre schéma

Titre de la section Utiliser les variables de votre schéma

Importez et utilisez vos variables définies à partir du module /client ou /server approprié :

---
import { API_URL } from "astro:env/client"
import { API_SECRET_TOKEN } from "astro:env/server"


const data = await fetch(`${API_URL}/users`, {
  method: "GET",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${API_SECRET_TOKEN}`
  },
})
---


<script>
import { API_URL } from "astro:env/client"


fetch(`${API_URL}/ping`)
</script>

Types de variables

Titre de la section Types de variables

Il existe trois types de variables d’environnement, déterminées par la combinaison des paramètres context (client ou serveur) et access (secret ou public) définis dans votre schéma :

  • Variables publiques du client : Ces variables se retrouvent à la fois dans vos bundles client et serveur finaux et sont accessibles à la fois depuis le client et le serveur via le module astro:env/client :

    import { API_URL } from "astro:env/client"

  • Variables publiques du serveur : Ces variables se retrouvent dans votre bundle de serveur final et sont accessibles sur le serveur via le module astro:env/server :

    import { PORT } from "astro:env/server"

  • Variables secrètes du serveur : Ces variables ne font pas partie de votre bundle final et sont accessibles sur le serveur via le module astro:env/server :

    import { API_SECRET } from "astro:env/server"

    Par défaut, les secrets ne sont validés qu’au moment de l’exécution. Vous pouvez activer la validation des variables privées au démarrage en configurant validateSecrets: true.

Types de données

Titre de la section Types de données

Il existe actuellement quatre types de données pris en charge : les chaînes de caractères, les nombres, les énumérations et les booléens :

import { envField } from "astro/config"


envField.string({
   // context & access
   optional: true,
   default: "foo",
})


envField.number({
   // context & access
   optional: true,
   default: 15,
})


envField.boolean({
   // context & access
   optional: true,
   default: true,
})


envField.enum({
   // context & access
   values: ['foo', 'bar', 'baz'],
   optional: true,
   default: 'baz',
})
Pour une liste complète des champs de validation, consultez la référence de l’API envField.

Récupérer des secrets de manière dynamique

Titre de la section Récupérer des secrets de manière dynamique

Malgré la définition de votre schéma, vous souhaiterez peut-être récupérer la valeur brute d’un secret donné ou récupérer des secrets non définis dans votre schéma. Dans ce cas, vous pouvez utiliser getSecret() exporté depuis astro:env/server :

import {
   FOO, // boolean
   getSecret
} from 'astro:env/server'


getSecret('FOO') // string | undefined
Apprenez-en davantage dans la référence de l’API.

Limitations

Titre de la section Limitations

  1. astro:env est un module virtuel, ce qui signifie qu’il ne peut être utilisé que dans le contexte Astro. Par exemple, vous pouvez l’utiliser dans :

    • les Middlewares
    • les routes et points de terminaison Astro
    • les composants Astro
    • les composants de framework
    • les modules

    Vous ne pouvez pas l’utiliser dans ce qui suit et devrez recourir à process.env :

    • astro.config.mjs
    • les scripts

  2. @astrojs/cloudflare est un peu différent des autres adaptateurs. Les variables d’environnement sont limitées à la requête, contrairement à Node.js où elles sont globales.

    Cela signifie que vous devez toujours utiliser des secrets dans la portée de la requête :

    src/middleware.ts
    import { defineMiddleware } from "astro:middleware"
    import { FOO, getSecret } from "astro:env"
    

    console.log(FOO) // undefined
    console.log(getSecret("FOO")) // undefined
    

    export const onRequest = defineMiddleware((context, next) => {
       console.log(FOO) // boolean
       console.log(getSecret("FOO")) // string
    

       return next()
    })
Contribuer

Comment pouvons-nous vous aider ?

Créer une issue GitHub

Le moyen le plus rapide d'alerter notre équipe d'un problème.

Communauté