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

# Déployer un serveur Mastra

Mastra compile votre application en un serveur Node.js autonome pouvant s'exécuter sur toute plateforme prenant en charge Node.js, Bun ou Deno.

> **Astuce:** Ce guide traite du déploiement du serveur autonome généré par `mastra build`. Si vous devez intégrer Mastra à une application Express ou Hono existante, consultez plutôt les [adaptateurs de serveur](https://mastra.zisheng.pro/fr/docs/server/server-adapters).

## Compiler votre application

Exécutez la commande de build depuis la racine de votre projet :

```bash
mastra build
```

Cette commande crée un répertoire `.mastra` contenant votre serveur prêt pour la production. Consultez la référence de [`mastra build`](https://mastra.zisheng.pro/fr/reference/cli/mastra) pour connaître toutes les options disponibles.

## Résultat du build

Après le build, Mastra crée la structure suivante :

```text
.mastra/
├── .build/                # Intermediate build artifacts (module maps, analysis)
└── output/
    ├── index.mjs          # Server entry point
    ├── mastra.mjs         # Your bundled Mastra configuration
    ├── tools.mjs          # Aggregated tool exports
    ├── tools/             # Individual tool bundles
    ├── package.json       # Production dependencies
    ├── node_modules/      # Installed dependencies
    ├── .npmrc             # Copied from your project (if present)
    ├── public/            # Static assets (if src/mastra/public exists)
    └── playground/        # Studio UI (if --studio flag used)
```

Le répertoire `output` est autonome. Vous pouvez le copier sur n'importe quel serveur et l'exécuter directement.

## Exécuter le serveur

Démarrez le serveur avec la CLI Mastra :

```bash
mastra start
```

Vous pouvez également l'exécuter directement avec Node.js :

```bash
node .mastra/output/index.mjs
```

La commande `mastra start` fournit des fonctionnalités supplémentaires :

- chargement des variables d'environnement depuis `.env.production` et `.env` ;
- messages d'erreur utiles en cas de modules manquants ;
- gestion des signaux du processus pour un arrêt propre.

Consultez la référence de [`mastra start`](https://mastra.zisheng.pro/fr/reference/cli/mastra) pour connaître toutes les options disponibles.

## Configuration du build

### Configuration au moment du build

Mastra lit les options `bundler`, `deployer` et `server` pendant le build de votre application. Conservez ces options comme propriétés directes de l'objet transmis à `new Mastra()` afin que le build puisse les extraire.

La structure de fichier d'entrée suivante fonctionne :

```typescript
import { Mastra } from '@mastra/core/mastra'

export const mastra = new Mastra({
  bundler: {
    externals: ['sharp'],
  },
  server: {
    port: 4111,
  },
})
```

La valeur de chaque option peut provenir d'une variable, d'un import ou d'un appel de fonction. L'option elle-même doit rester une propriété directe. Ne masquez pas les options de build derrière un appel de fabrique ou une décomposition d'objet :

```typescript
const options = {
  bundler: {
    externals: ['sharp'],
  },
}

// These patterns prevent Mastra from extracting `bundler` during the build.
export const mastra = new Mastra(createMastraOptions())
export const otherMastra = new Mastra({ ...options })
```

Lorsque Mastra ne peut pas extraire une option, il applique le comportement de build par défaut pour celle-ci. Consultez la [référence de configuration](https://mastra.zisheng.pro/fr/reference/configuration) pour les paramètres `bundler`, `deployer` et `server` disponibles.

### Dossier public

Si un dossier `public` existe dans votre répertoire Mastra (`src/mastra/public`), son contenu est copié dans le répertoire de sortie pendant le build. Le serveur distribue ces fichiers comme ressources statiques.

### Configuration de Mastra

Le processus de build respecte la configuration de votre instance Mastra. Pour le comportement du serveur, notamment CORS, les délais d'expiration et les middlewares, consultez la [présentation du serveur](https://mastra.zisheng.pro/fr/docs/server/mastra-server). Pour toutes les options disponibles, consultez la [référence de configuration](https://mastra.zisheng.pro/fr/reference/configuration).

## Processus de build

Le build suit les étapes suivantes :

1. **Localisation du fichier d'entrée** : recherche `index.ts` ou `index.js` dans votre répertoire Mastra.
2. **Découverte des outils** : recherche les fichiers d'outils correspondant à `{mastraDir}/tools/**/*.{js,ts}`, en excluant les fichiers de test.
3. **Analyse des dépendances** : détermine quels packages regrouper et lesquels installer séparément.
4. **Regroupement du code** : utilise Rollup avec élimination du code mort et, facultativement, des source maps.
5. **Génération du serveur** : crée un serveur HTTP basé sur Hono sous la forme `index.mjs`.
6. **Installation des dépendances** : exécute `npm install` dans le répertoire de sortie.
7. **Copie des ressources** : copie le dossier `public` et le fichier `.npmrc` s'ils existent.

## Variables d'environnement

| Variable             | Description                                                                                               |
| -------------------- | --------------------------------------------------------------------------------------------------------- |
| `PORT`               | Port du serveur (par défaut : `4111`)                                                                     |
| `MASTRA_STUDIO_PATH` | Chemin du répertoire de build de Studio (par défaut : `./playground`)                                     |
| `MASTRA_SKIP_DOTENV` | Ignore le chargement des fichiers `.env` lorsqu'elle est définie                                          |
| `NODE_OPTIONS`       | Options Node.js (par exemple `--max-old-space-size=4096` en cas de problèmes de mémoire pendant le build) |

## Points de terminaison du serveur

Le serveur compilé expose des points de terminaison pour les contrôles de santé, les Agents, les Workflows et bien plus :

| Point de terminaison    | Description                                                                 |
| ----------------------- | --------------------------------------------------------------------------- |
| `GET /health`           | Point de terminaison de contrôle de santé, renvoie `200 OK`                 |
| `GET /api/openapi.json` | Spécification OpenAPI (si `server.build.openAPIDocs` est activé).           |
| `GET /swagger-ui`       | Documentation interactive de l'API (si `server.build.swaggerUI` est activé) |

Cette liste n'est pas exhaustive. Pour afficher tous les points de terminaison, exécutez `mastra dev` puis ouvrez `http://localhost:4111/swagger-ui`.

Pour ajouter vos propres points de terminaison, consultez les [routes d'API personnalisées](https://mastra.zisheng.pro/fr/docs/server/custom-api-routes).

## Dépannage

### Erreurs de mémoire pendant le build

Si vous rencontrez des erreurs `JavaScript heap out of memory` :

```bash
NODE_OPTIONS="--max-old-space-size=4096" mastra build
```

## Voir aussi

- [Présentation du serveur](https://mastra.zisheng.pro/fr/docs/server/mastra-server) : configurer le comportement du serveur, les middlewares et l'authentification
- [Adaptateurs de serveur](https://mastra.zisheng.pro/fr/docs/server/server-adapters) : utiliser Express ou Hono à la place de `mastra build`
- [Routes d'API personnalisées](https://mastra.zisheng.pro/fr/docs/server/custom-api-routes) : ajouter des points de terminaison HTTP personnalisés
- [Référence de configuration](https://mastra.zisheng.pro/fr/reference/configuration) : toutes les options de configuration