> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# Déployer sur Mastra Platform

[`mastra deploy`](https://mastra.zisheng.pro/fr/reference/cli/mastra) est la commande unique qui permet de publier une application Mastra sur [Mastra Platform](https://mastra.zisheng.pro/fr/docs/mastra-platform/overview).

Une seule commande compile et valide votre projet avant tout envoi. Lors de la première exécution, elle crée également le projet et l’environnement sur la plateforme, lance le déploiement, diffuse les journaux de compilation et affiche votre URL publique dès que le déploiement reçoit du trafic.

```bash
mastra deploy
```

> **Remarque:** Cette page décrit le flux de déploiement unifié. Les anciennes commandes distinctes, [`mastra server deploy`](https://mastra.zisheng.pro/fr/docs/mastra-platform/server) et [`mastra studio deploy`](https://mastra.zisheng.pro/fr/docs/mastra-platform/studio), fonctionnent toujours, mais `mastra deploy` constitue la méthode recommandée.

## Avant de commencer

Vous avez besoin d’une [application Mastra](https://mastra.zisheng.pro/fr/guides/getting-started/quickstart) et d’un compte [Mastra Platform](https://projects.mastra.ai). Si vous n’êtes pas authentifié, la CLI vous invite à vous connecter lors de la première utilisation.

Un fichier `.env` local est facultatif. Les variables d’environnement stockées sur la plateforme sont utilisées telles quelles lors du déploiement, et les ressources gérées comme les [bases de données hébergées](https://mastra.zisheng.pro/fr/docs/mastra-platform/database) injectent leurs propres variables. Transmettez `--env-file` uniquement lorsque vous souhaitez ajouter des valeurs locales par-dessus.

## Votre premier déploiement

1. Depuis le répertoire de votre projet, exécutez :

   ```bash
   mastra deploy
   ```

   Lors de la première exécution, la CLI vous invite à créer le projet sur la plateforme, nommé d’après votre `package.json`, ainsi que l’environnement `production`. Acceptez les invites ou transmettez `--yes` pour accepter les valeurs par défaut sans confirmation.

2. La CLI effectue une vérification préalable avant tout envoi. Un stockage qui se rabattrait sur un chemin de fichier local, lequel ne survit pas dans le système de fichiers éphémère de la plateforme, bloquerait normalement le déploiement :

   ```text
   file:./mastra.db will be used at runtime because TURSO_DATABASE_URL is not set
   ```

   Au lieu de renvoyer une erreur, la CLI vous propose de corriger le problème directement :

   ```text
   Preflight needs TURSO_DATABASE_URL for the production environment. Create a managed turso database now and attach it? (Y/n)
   ```

   Acceptez l’invite : le provisionnement ne prend que quelques secondes et les variables de connexion de la base de données sont automatiquement injectées dans vos déploiements, sans rien avoir à copier dans un fichier `.env`. Si vous refusez ou exécutez la commande dans un shell non interactif (CI, `--yes`), la CLI reprend son comportement précédent et affiche la commande exacte à exécuter vous-même.

   ```bash
   mastra env db create production --kind turso
   ```

   Le slug de l’environnement (`production` ci-dessus) correspond à l’environnement dans lequel la CLI aurait effectué le déploiement. Ce point est important, car `mastra env db create` nécessite un argument d’environnement dans les shells non interactifs lorsque le projet comporte plusieurs environnements.

   > **Remarque:** Si la vérification préalable signale plutôt un chemin local codé en dur (`Build contains a host-local storage URL`), elle ne peut pas proposer de correction directe. Commencez par protéger ce chemin avec une variable d’environnement afin que le fichier ne soit utilisé que pendant le développement local :
   >
   > ```ts
   > new LibSQLStore({
   >   id: 'mastra-storage',
   >   // Uses the hosted database when deployed, a local file during development
   >   url: process.env.TURSO_DATABASE_URL ?? 'file:./mastra.db',
   >   authToken: process.env.TURSO_AUTH_TOKEN,
   > })
   > ```

3. Exécutez de nouveau `mastra deploy`. La vérification préalable réussit, la compilation est envoyée et la CLI diffuse les journaux de compilation jusqu’à la mise en ligne du déploiement. La compilation et le déploiement complets prennent entre 30 secondes et quelques minutes. Le message de réussite ne s’affiche que lorsque la nouvelle version reçoit du trafic.

4. Vérifiez votre déploiement à l’URL affichée par la CLI. Ajoutez `/api/agents` pour confirmer qu’elle renvoie une liste JSON de vos agents.

   > **Attention:** Configurez l’[authentification](https://mastra.zisheng.pro/fr/docs/server/auth) avant d’exposer publiquement vos endpoints.

Le premier déploiement écrit un fichier `.mastra-project.json` qui relie votre répertoire au projet de la plateforme. Validez ce fichier dans votre dépôt afin que les déploiements ultérieurs, les exécutions de CI et les commandes [`mastra env`](https://mastra.zisheng.pro/fr/docs/mastra-platform/environments) ciblent le même projet sans option supplémentaire.

## Déployer dans un autre environnement

`mastra deploy` cible par défaut l’environnement `production`. Transmettez `--env` pour en cibler un autre. Si l’environnement n’existe pas encore, la CLI vous propose de le créer :

```bash
mastra deploy --env staging
```

Chaque environnement dispose de sa propre URL et de ses propres variables d’environnement. Il peut également posséder sa propre [base de données hébergée](https://mastra.zisheng.pro/fr/docs/mastra-platform/database).

Consultez la page [Environnements](https://mastra.zisheng.pro/fr/docs/mastra-platform/environments) pour découvrir le modèle complet.

## Choisir une région

Transmettez `--region` lorsqu’un déploiement crée un nouvel environnement afin de choisir où il s’exécute. Utilisez les formes abrégées `us` ou `eu` :

```bash
mastra deploy --env production --region eu
```

La région est fixée lors de la création de l’environnement. Les bases de données rattachées à un environnement sont automatiquement placées à proximité de sa région, et les données d’observabilité sont routées vers la région d’ingestion correspondant à la zone de résidence de l’environnement. Consultez la page [Régions](https://mastra.zisheng.pro/fr/docs/mastra-platform/regions) pour obtenir la liste complète des régions prises en charge ainsi que des informations sur le placement des bases de données et la colocalisation des données d’observabilité.

## Vérifications préalables

La vérification préalable valide le résultat de la compilation avant tout envoi et signale uniquement les problèmes présents dans votre propre code :

- **Chemins de stockage locaux** : il s’agit d’une erreur bloquante. Le stockage reposant sur des fichiers, par exemple `file:./mastra.db`, est perdu à chaque déploiement. La vérification préalable réussit lorsque le chemin est protégé par une variable d’environnement définie localement, stockée sur la plateforme ou fournie par une base de données gérée :

  ```ts
  import { LibSQLStore } from '@mastra/libsql'

  export const storage = new LibSQLStore({
    id: 'mastra-storage',
    // Uses the hosted database when deployed, a local file during development
    url: process.env.TURSO_DATABASE_URL ?? 'file:./mastra.db',
    authToken: process.env.TURSO_AUTH_TOKEN,
  })
  ```

- **Variables d’environnement manquantes** : un avertissement est émis pour les variables que votre code lit, mais qu’aucune source ne fournit. Les variables référencées uniquement par du code de bibliothèque sont exclues.

La réponse recommandée à un blocage de la vérification préalable consiste à en corriger la cause, généralement en rattachant une base de données hébergée ou en stockant la variable sur la plateforme. `--skip-preflight` offre une solution de secours, mais ignore les vérifications qui empêchent les déploiements défectueux.

Exécutez les vérifications sans effectuer de déploiement :

```bash
mastra lint --preflight
```

`mastra lint` voit uniquement vos fichiers d’environnement locaux. Les variables stockées sur la plateforme ou injectées par des bases de données gérées ne lui sont pas visibles ; un déploiement peut donc réussir la vérification préalable alors que lint signale toujours une erreur.

## Variables d’environnement

Les déploiements résolvent les variables d’environnement à partir de trois sources :

- **Variables gérées** : injectées par des ressources de la plateforme telles que les bases de données hébergées, par exemple `TURSO_DATABASE_URL`. La plateforme les définit et vous ne pouvez pas les modifier.
- **Variables stockées** : enregistrées sur le projet ou l’environnement depuis le tableau de bord. Elles sont utilisées telles quelles à chaque déploiement, sans nécessiter de fichier local.
- **Fichiers d’environnement locaux** : les déploiements superposent un fichier `--env-file` explicite ou les fichiers `.env` et `.env.local` présents dans l’environnement local.

```bash
mastra deploy --env staging --env-file .env.staging
```

Pour modifier les variables d’un service en cours d’exécution sans le redéployer, mettez-les à jour dans le tableau de bord, puis exécutez [`mastra env restart`](https://mastra.zisheng.pro/fr/reference/cli/mastra).

## Résolution du projet

Chaque déploiement résout son projet cible dans l’ordre suivant :

1. La variable d’environnement `MASTRA_PROJECT_ID`
2. L’option `--project <name|slug|id>`
3. Le fichier `.mastra-project.json` dans le répertoire actuel

Dans la CI, définissez `MASTRA_PROJECT_ID` et `MASTRA_API_TOKEN`, puis transmettez `--yes` :

```bash
mastra deploy --env production --yes
```

## Ressources associées

- [Environnements](https://mastra.zisheng.pro/fr/docs/mastra-platform/environments)
- [Régions](https://mastra.zisheng.pro/fr/docs/mastra-platform/regions)
- [Bases de données hébergées](https://mastra.zisheng.pro/fr/docs/mastra-platform/database)
- [Référence CLI de `mastra deploy`](https://mastra.zisheng.pro/fr/reference/cli/mastra)
- [Configuration](https://mastra.zisheng.pro/fr/docs/mastra-platform/configuration)