Déployer votre site Astro sur Cloudflare

Vous pouvez déployer des applications full-stack, y compris des ressources statiques front-end et des API back-end, ainsi que des sites rendus à la demande, sur Cloudflare Workers.

:::note

Cloudflare recommande d'utiliser Cloudflare Workers pour les nouveaux projets. Pour les projets Pages existants, consultez le guide de migration de Cloudflare et la matrice de compatibilité.

:::

En savoir plus sur l'utilisation de l'environnement d'exécution Cloudflare dans votre projet Astro.

Prérequis

Pour commencer, vous aurez besoin :

Un compte Cloudflare. Si vous n'en avez pas encore, vous pouvez créer un compte Cloudflare gratuit au cours de la procédure.

Cloudflare Workers

Comment déployer à l'aide de Wrangler

Installez la CLI de Wrangler.
```
npm install wrangler@latest --save-dev
```
Si votre site utilise le rendu à la demande, installez l'adaptateur @astrojs/cloudflare.

Cela installera l'adaptateur et apportera les modifications appropriées à votre fichier astro.config.mjs en une seule étape.
- npm
- pnpm
- Yarn
```
npx astro add cloudflare
```
```
pnpm astro add cloudflare
```
```
yarn astro add cloudflare
```
En savoir plus sur le rendu à la demande dans Astro.
Créez un fichier de configuration Wrangler.

L'exécution de astro add cloudflare créera ceci pour vous ; si vous n'utilisez pas l'adaptateur, vous devrez le créer vous-même.
- Statique
- SSR
```
  {
    "name": "mon-appli-astro",
    "compatibility_date": "2025-03-25", // Mettre à jour avec le jour de votre déploiement
    "assets": {
      "directory": "./dist",
    }
  }
```
```
  {
    "main": "./dist/_worker.js/index.js",
    "name": "mon-appli-astro",
    "compatibility_date": "2025-03-25", // Mettre à jour avec le jour de votre déploiement
    "compatibility_flags": [
      "nodejs_compat",
      "global_fetch_strictly_public"
    ],
    "assets": {
      "binding": "ASSETS",
      "directory": "./dist"
    },
    "observability": {
      "enabled": true
    }
  }
```
Prévisualisez votre projet localement avec Wrangler.
```
npx astro build && npx wrangler dev
```
Déployez en utilisant npx wrangler deploy.
```
npx astro build && npx wrangler deploy
```

Une fois vos ressources téléchargées, Wrangler vous donnera une URL de prévisualisation pour inspecter votre site.

En savoir plus sur l'utilisation des API de l'environnement d'exécution Cloudflare telles que les liaisons.

Comment déployer avec CI/CD

Vous pouvez également utiliser un système CI/CD tel que Workers Builds pour créer et déployer automatiquement votre site après un « push ».

Si vous utilisez Workers Builds :

Suivez les étapes 1 à 3 de la section Wrangler ci-dessus.
Connectez-vous au tableau de bord Cloudflare et accédez à Compute > Workers & Pages. Sélectionnez Create application.
Sous Import a repository, sélectionnez un compte Git puis le dépôt contenant votre projet Astro.
Configurez votre projet avec :
- Build command : npx astro build
- Deploy command : npx wrangler deploy
Cliquez sur Save and Deploy. Vous pouvez maintenant prévisualiser votre Worker dans son sous-domaine workers.dev fourni.

Dépannage

Comportement 404

Pour les projets Workers, vous devrez définir « not_found_handling » si vous souhaitez afficher une page 404 personnalisée. Vous pouvez en savoir plus à ce sujet dans la section Comportement du routage de la documentation de Cloudflare.

{
  "assets": {
    "directory": "./dist",
    "not_found_handling": "404-page"
  }
}

Hydratation côté client

L'hydratation côté client peut échouer à cause du paramètre Auto Minify de Cloudflare. Si vous voyez Hydration completed but contains mismatches dans la console, assurez-vous de désactiver Auto Minify dans les paramètres de Cloudflare.

API de l'environnement d'exécution Node.js

Si vous créez un projet qui utilise le rendu à la demande avec l'adaptateur Cloudflare et que le serveur ne parvient pas à construire avec un message d'erreur tel que [Error] Could not resolve "XXXX. The package "XXXX" wasn't found on the file system but is built into node. :

Cela signifie qu'un paquet ou une importation que vous utilisez dans l'environnement côté serveur n'est pas compatible avec les API de l'environnement d'exécution Cloudflare.
Si vous importez directement une API de l'environnement d'exécution Node.js, veuillez consulter la documentation Astro sur la compatibilité Node.js de Cloudflare pour savoir comment résoudre ce problème.
Si vous importez un paquet qui importe une API de l'environnement d'exécution Node.js, vérifiez avec l'auteur du paquet s'il prend en charge la syntaxe d'importation node:*. Si ce n'est pas le cas, vous devrez peut-être trouver un autre paquet.