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 et Cloudflare Pages.

Ce guide comprend :

Comment déployer sur Cloudflare Workers
Comment déployer sur Cloudflare Pages

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.
Fenêtre du terminal
```
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
Fenêtre du terminal
npx astro add cloudflare
Fenêtre du terminal
pnpm astro add cloudflare
Fenêtre du terminal
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
wrangler.jsonc
{ "name": "mon-appli-astro", "compatibility_date": "2025-03-25", // Mettre à jour avec le jour de votre déploiement "assets": { "binding": "ASSETS", "directory": "./dist", } }
wrangler.jsonc
{ "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.
Fenêtre du terminal
```
npx astro build && npx wrangler dev
```
Déployez en utilisant npx wrangler deploy.
Fenêtre du terminal
```
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 (BETA) 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 à Workers & Pages. Sélectionnez Create.
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.

Cloudflare Pages

Comment déployer à l’aide de Wrangler

Installez la CLI de Wrangler.

npm install wrangler@latest --save-dev

pnpm add wrangler@latest --save-dev

yarn add wrangler@latest --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
Fenêtre du terminal
npx astro add cloudflare
Fenêtre du terminal
pnpm astro add cloudflare
Fenêtre du terminal
yarn astro add cloudflare
Créez un fichier de configuration Wrangler.

Étant donné que Cloudflare recommande aux nouveaux projets d’utiliser Workers au lieu de Pages, la commande astro add cloudflare crée les fichiers wrangler.jsonc et public/.assetsignore, qui sont spécifiques aux projets Workers. Vous devrez supprimer le fichier public/.assetsignore et modifier votre fichier wrangler.jsonc. Si vous n’utilisez pas l’adaptateur, vous devrez le créer vous-même.

Assurez-vous que votre fichier wrangler.jsonc est structuré comme ceci :
- Statique
- SSR
wrangler.jsonc
{ "name": "mon-appli-astro", "compatibility_date": "YYYY-MM-DD", // Mettre à jour avec le jour de votre déploiement "pages_build_output_dir": "./dist" }
wrangler.jsonc
{ "name": "mon-appli-astro", "compatibility_date": "YYYY-MM-DD", // Mettre à jour avec le jour de votre déploiement "compatibility_flags": [ "nodejs_compat", "disable_nodejs_process_v2" ], "pages_build_output_dir": "./dist" }
En savoir plus sur le rendu à la demande dans Astro.

Prévisualisez votre projet localement avec Wrangler.

npx astro build && wrangler pages dev ./dist

pnpm astro build && wrangler pages dev ./dist

yarn astro build && wrangler pages dev ./dist

Déployez en utilisant npx wrangler deploy.

npx astro build && wrangler pages deploy ./dist

pnpm astro build && wrangler pages deploy ./dist

yarn astro build && wrangler pages deploy ./dist

Une fois vos ressources téléchargées, Wrangler vous fournira une URL d’aperçu pour inspecter votre site.

Comment déployer un site en utilisant le CI/CD

Envoyez votre code vers votre dépôt Git (par exemple GitHub, GitLab).
Connectez-vous au tableau de bord de Cloudflare et accédez à Compute (Workers) > Workers & Pages. Sélectionnez Create, puis l’onglet Pages. Connectez votre dépôt Git.
Configurez votre projet avec :
- Framework preset: Astro
- Build command: npm run build
- Build output directory: dist
Cliquez sur le bouton Save and deploy.

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"
  }
}

Pour les projets Pages, si vous incluez une page 404 personnalisée, elle sera affichée par défaut. Sinon, Pages adoptera par défaut le comportement de rendu d’application monopage de Cloudflare et redirigera vers la page d’accueil au lieu d’afficher une page 404.

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.

Plus de guides de déploiement

Contribuer Communauté Parrainer