@astrojs/ cloudflare
Cet adaptateur permet à Astro de déployer votre site rendu hybrid
ou server
(EN) sur Cloudflare.
Si vous utilisez Astro comme constructeur de sites statiques, vous n’avez pas besoin d’adaptateur.
Découvrez comment déployer votre site Astro dans notre Guide de déploiement des pages Cloudflare.
Pourquoi Astro Cloudflare
Titre de la section Pourquoi Astro CloudflareCloudflare fournit des CDN, de la sécurité web et d’autres services. Cet adaptateur améliore le processus de construction d’Astro pour préparer votre projet à être déployé via Cloudflare.
Installation
Titre de la section InstallationAstro inclut une commande astro add
pour automatiser l’installation des intégrations officielles. Si vous préférez, vous pouvez installer les intégrations manuellement à la place.
Ajoutez l’adaptateur Cloudflare pour activer SSR dans votre projet Astro avec la commande astro add
. Cela installera @astrojs/cloudflare
et apportera les changements appropriés à votre fichier astro.config.mjs
en une seule étape.
Installation manuelle
Titre de la section Installation manuelleTout d’abord, ajoutez l’adaptateur @astrojs/cloudflare
aux dépendances de votre projet en utilisant votre gestionnaire de paquets préféré.
Ensuite, ajoutez l’adaptateur et votre mode de rendu à la demande (EN) à votre fichier astro.config.mjs
:
Options
Titre de la section OptionsimageService
Titre de la section imageServiceType : 'passthrough' | 'cloudflare' | 'compile' | 'custom'
Par défaut : 'compile'
Détermine quel service d’image est utilisé par l’adaptateur. L’adaptateur utilisera par défaut le mode compile
si un service d’image incompatible est configuré. Sinon, il utilisera le service d’image configuré globalement :
cloudflare
: Utilise le service Cloudflare Image Resizing.passthrough
: Utilise le service existantnoop
.compile
: Utilise le service par défaut d’Astro (sharp), mais seulement sur les routes pré-rendues au moment de la compilation. Pendant le SSR pour les pages rendues à la demande, toutes les fonctionnalités deastro:assets
sont désactivées.custom
: Utilise toujours le service d’image configuré dans Image Options. **Cette option ne vérifie pas si le service d’image configuré fonctionne dans le moteur d’exécutionworkerd
de Cloudflare.
platformProxy
Titre de la section platformProxyDétermine la façon dont le runtime Cloudflare est ajouté à astro dev
. Il contient des proxies vers les bindings locaux workerd
et des émulations de valeurs spécifiques à Cloudflare, permettant l’émulation du runtime dans le processus de développement Node.js. En savoir plus sur le Cloudflare Runtime.
Les proxies fournis par ce site sont une émulation au mieux de la production réelle. Bien qu’ils soient conçus pour être aussi proches que possible de la réalité, il peut y avoir de légères différences et incohérences entre les deux.
platformProxy.enabled
Titre de la section platformProxy.enabledType : { enabled?: boolean }
Par défaut : { enabled: false }
La propriété enabled
vous permet d’activer le runtime Cloudflare dans astro dev
.
platformProxy.configPath
Titre de la section platformProxy.configPathType : { configPath?: string }
Par défaut : { configPath: 'wrangler.toml' }
Le configPath
vous permet de définir votre fichier de configuration Wrangler, relatif à la racine de votre projet Astro.
platformProxy.experimentalJsonConfig
Titre de la section platformProxy.experimentalJsonConfigType : { experimentalJsonConfig?: boolean }
Par défaut : { experimentalJsonConfig?: false }
La propriété experimentalJsonConfig
définit si l’utilitaire lit un fichier de configuration JSON (par exemple wrangler.json
).
platformProxy.persist
Titre de la section platformProxy.persistType : { persist?: boolean | { path: string } }
Par défaut : { persist: true }
La propriété persist
définit si et où les données des bindings sont persistantes. Par défaut, true
est le même emplacement que celui utilisé par Wrangler afin que les données puissent être partagées entre les deux. Si false
, aucune donnée n’est persistée ou lue depuis le système de fichiers.
L’option --persist-to
de wrangler
ajoute un sous-répertoire appelé v3
sous le capot alors que la propriété @astrojs/cloudflare
persist
ne le fait pas. Par exemple, pour réutiliser le même emplacement qu’en lançant wrangler dev --persist-to ./mon-dossier
, vous devez spécifier : persist : "./mon-dossier/v3"
.
La configuration suivante montre un exemple d’activation du runtime Cloudflare lors de l’exécution du serveur de développement, ainsi que l’utilisation d’un fichier de configuration wrangler.json
(expérimental). Elle spécifie également un emplacement personnalisé pour la persistance des données dans le système de fichiers :
routes.extend
Titre de la section routes.extendCette option vous permet d’ajouter ou d’exclure des motifs personnalisés (par exemple /fonts/*
) au fichier _routes.json
généré qui détermine quelles routes sont générées à la demande. Cela peut être utile si vous avez besoin d’ajouter des modèles de route qui ne peuvent pas être générés automatiquement, ou d’exclure des routes pré-rendues.
Vous trouverez plus d’informations sur les modèles de routes personnalisées dans la documentation de routing de Cloudflare. Les routes spécifiées ne sont pas automatiquement dédupliquées et seront ajoutées telles quelles aux routes existantes.
routes.extend.include
Titre de la section routes.extend.includeType : { pattern: string }[]
Par défaut : undefined
Configurez des routes supplémentaires qui seront générées à la demande par l’adaptateur Cloudflare dans le tableau routes.extend.include
.
routes.extend.exclude
Titre de la section routes.extend.excludeType : { pattern: string }[]
Par défaut : undefined
Configure les routes à exclure du rendu à la demande dans le tableau routes.extend.exclude
. Ces routes seront pré-rendues et servies statiquement à la place, et n’invoqueront pas la fonction SSR. De plus, vous pouvez utiliser cette option pour servir n’importe quel fichier statique (images, polices, css, js, html, txt, json, etc.) directement sans faire passer la requête par la fonction SSR.
cloudflareModules
Titre de la section cloudflareModulesType : true | false
Par défaut : true
Active les importations des modules .wasm
, .bin
, et .txt
.
Cette fonctionnalité est activée par défaut. Si vous souhaitez la désactiver, définissez cloudflareModules : false
.
Cloudflare runtime
Titre de la section Cloudflare runtimeLe moteur d’exécution de Cloudflare vous donne accès aux variables d’environnement et aux liaisons de Cloudflare.
Le moteur d’exécution de Cloudflare utilise les liaisons trouvées dans les fichiers de configuration wrangler
et .dev.vars
.
Utilisation
Titre de la section UtilisationPar exemple, si vous avez une variable d’environnement configurée dans wrangler.toml
:
Si vous avez besoin de définir des secrets
en plus des variables d’environnement, vous devez ajouter un fichier .dev.vars
à la racine du projet Astro :
Vous pouvez accéder aux bindings en utilisant les localisations Astro comme suit :
Vous pouvez accéder à l’exécution à partir des points d’extrémité de l’API par l’intermédiaire de context.locals
:
Pour accéder à la valeur de la liaison MY_VARIABLE
, ajoutez ce qui suit à votre code :
Voir la liste de toutes les liaisons prises en charge dans la documentation de Cloudflare.
wrangler
fournit une commande types
pour générer des types TypeScript pour les bindings. Cela vous permet de taper des éléments locaux sans avoir besoin de les taper manuellement. Référez-vous à la documentation de Cloudflare pour plus d’informations.
Chaque fois que vous modifiez vos fichiers de configuration (par exemple wrangler.toml
, .dev.vars
), vous devez lancer wrangler types
.
Vous pouvez créer un script pnpm pour lancer wrangler types
automatiquement avant d’autres commandes.
Vous pouvez taper l’objet runtime
en utilisant Runtime
:
Plate-forme Cloudflare
Titre de la section Plate-forme CloudflareHeaders
Titre de la section HeadersVous pouvez attacher des en-têtes personnalisés à vos réponses en ajoutant un fichier _headers
dans le dossier public/
de votre projet Astro. Ce fichier sera copié dans le répertoire de sortie de la compilation.
Les assets construits par Astro sont tous nommés avec un hash et peuvent donc se voir attribuer de longs en-têtes de cache. Par défaut, Astro sur Cloudflare ajoutera un en-tête de ce type pour ces fichiers.
Redirects
Titre de la section RedirectsVous pouvez déclarer des redirections personnalisées en utilisant les pages Cloudflare. Cela vous permet de rediriger les requêtes vers une URL différente. Vous pouvez ajouter un fichier _redirects
dans le dossier public/
de votre projet Astro. Ce fichier sera copié dans le répertoire de sortie de votre build.
Routage de Cloudflare utilise un fichier _routes.json
pour déterminer quelles requêtes sont routées vers la fonction SSR et lesquelles sont servies en tant qu’actifs statiques. Par défaut, un fichier _routes.json
sera automatiquement généré pour votre projet en fonction de ses fichiers et de sa configuration.
Vous pouvez spécifier des modèles de routage supplémentaires à suivre dans la configuration de votre adaptateur, ou créer votre propre fichier _routes.json
personnalisé pour ignorer complètement la génération automatique.
_routes.json
personnalisé
Titre de la section _routes.json personnaliséLa création d’un public/_routes.json
personnalisé annulera la génération automatique. Voir la documentation de Cloudflare sur la création d’un _routes.json
personnalisé pour plus de détails.
Importations de modules Cloudflare
Titre de la section Importations de modules CloudflareLe moteur d’exécution cloudflare worker prend en charge les importations de certains types de modules non standard. La plupart des types de fichiers supplémentaires sont également disponibles dans astro :
.wasm
ou.wasm?module
: exporte unWebAssembly.Module
qui peut ensuite être instancié..bin
: exporte unArrayBuffer
du contenu binaire brut du fichier.txt
: Exporte une chaîne de caractères du contenu du fichier
Tous les types de modules exportent une seule valeur par défaut. Les modules peuvent être importés à partir de pages affichées côté serveur ou de pages pré-rendues pour la génération de sites statiques.
Voici un exemple d’importation d’un module Wasm qui répond aux requêtes en additionnant les paramètres numériques de la requête.
Bien que cet exemple soit trivial, Wasm peut être utilisé pour accélérer des opérations de calcul intensif qui n’impliquent pas d’E/S importantes, comme l’intégration d’une bibliothèque de traitement d’images, ou l’intégration d’une petite base de données pré-indexée pour la recherche sur un ensemble de données en lecture seule.
Compatibilité Node.js
Titre de la section Compatibilité Node.jsCloudflare ne prend pas en charge les API d’exécution Node.js. Avec un peu de configuration, Cloudflare prend en charge un sous-ensemble des API d’exécution Node.js. Vous pouvez trouver les API d’exécution Node.js prises en charge dans la documentation de Cloudflare.
Pour utiliser ces API, votre page ou votre point d’accès doit être affiché côté serveur (et non pré-rendu) et doit utiliser la syntaxe d’importation import {} from 'node:*'
.
Vous devrez également modifier la configuration vite
dans votre astro config pour autoriser la syntaxe d’importation node:*
:
En plus de cela, vous devrez suivre la documentation de Cloudflare sur la façon d’activer le support. Pour des conseils détaillés, veuillez vous référer à la documentation Cloudflare sur l’activation de la compatibilité Node.js.
Si un projet importe un paquetage dans le serveur qui utilise les API d’exécution Node.js, cela peut causer des problèmes lors du déploiement sur Cloudflare. Ce problème survient avec les paquets qui n’utilisent pas la syntaxe d’importation node:*
. Il est recommandé de contacter les auteurs du paquetage pour déterminer si le paquetage supporte la syntaxe d’importation ci-dessus. Si ce n’est pas le cas, vous devrez peut-être utiliser un autre paquet.
Aperçu avec Wrangler
Titre de la section Aperçu avec WranglerPour utiliser wrangler
afin d’exécuter votre application localement, mettez à jour le script de prévisualisation :
wrangler
vous donne accès aux liaisons Cloudflare, aux variables d’environnement, et à l’objet cf. Faire fonctionner le rechargement à chaud (Hot Reloading) du serveur de développement d’Astro avec Wrangler peut nécessiter une configuration personnalisée. Voir les exemples de la communauté.
Messages d’erreur significatifs
Titre de la section Messages d’erreur significatifsActuellement, les erreurs lors de l’exécution de votre application dans Wrangler ne sont pas très utiles, en raison de la minification de votre code. Pour un meilleur débogage, vous pouvez ajouter le paramètre vite.build.minify = false
à votre astro.config.mjs
.