| type | title | description | githubIntegrationURL | category | i18nReady |
|---|---|---|---|---|---|
integration |
@astrojs/cloudflare |
Apprendre à utiliser l'adaptateur SSR @astrojs/cloudflare pour déployer votre projet Astro. |
adapter |
true |
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
Cet adaptateur permet à Astro de déployer votre site rendu hybrid ou server 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.
Cloudflare 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.
Astro 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.
Tout 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 à votre fichier astro.config.mjs :
import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';
export default defineConfig({
output: 'server',
adapter: cloudflare(),
});
**Type :** `'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:assetssont 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écutionworkerdde Cloudflare.
import {defineConfig} from "astro/config";
import cloudflare from '@astrojs/cloudflare';
export default defineConfig({
adapter: cloudflare({
imageService: 'cloudflare'
}),
output: 'server'
})Dé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.
:::note 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. :::
**Type :** `{ enabled?: boolean }`
**Par défaut :** `{ enabled: false }`
La propriété enabled vous permet d'activer le runtime Cloudflare dans astro dev.
**Type :** `{ 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.
**Type :** `{ 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).
**Type :** `{ 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.
:::note
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 :
import cloudflare from '@astrojs/cloudflare';
import { defineConfig } from 'astro/config';
export default defineConfig({
adapter: cloudflare({
platformProxy: {
enabled: true,
configPath: 'wrangler.json',
experimentalJsonConfig: true,
persist: './.cache/wrangler/v3',
},
}),
});Cette 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.
**Type :** `{ 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.
**Type :** `{ 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.
export default defineConfig({
adapter: cloudflare({
routes: {
extend: {
include: [{ pattern: '/static' }], // Achemine une page pré-établie vers la fonction SSR pour l'afficher à la demande
exclude: [{ pattern: '/pagefind/*' }], // Utilise la recherche pagefind de Starlight, qui est générée statiquement au moment de la construction.
}
},
}),
});
**Type :** `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.
Le 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.
Par exemple, si vous avez une variable d'environnement configurée dans wrangler.toml :
[vars]
MY_VARIABLE = "test"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 :
DB_PASSWORD=myPasswordVous pouvez accéder aux bindings en utilisant les localisations Astro comme suit :
---
const { env } = Astro.locals.runtime;
---Vous pouvez accéder à l'exécution à partir des points d'extrémité de l'API par l'intermédiaire de context.locals :
export function GET(context) {
const runtime = context.locals.runtime;
return new Response('Un corps de réponse');
}Pour accéder à la valeur de la liaison MY_VARIABLE, ajoutez ce qui suit à votre code :
---
const { env } = Astro.locals.runtime;
const myVariable = env.MY_VARIABLE;
---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.
:::note
Vous pouvez créer un script pnpm pour lancer wrangler types automatiquement avant d'autres commandes.
{
"scripts": {
"dev": "wrangler types && astro dev",
"start": "wrangler types && astro dev",
"build": "wrangler types && astro check && astro build",
"preview": "wrangler types && astro preview",
"astro": "astro"
}
}:::
Vous pouvez taper l'objet runtime en utilisant Runtime :
/// <reference types="astro/client" />
type Runtime = import('@astrojs/cloudflare').Runtime<Env>;
declare namespace App {
interface Locals extends Runtime {
otherLocals: {
test: string;
};
}
}Vous 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.
Vous 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.
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.
Le 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 :
.wasmou.wasm?module: exporte unWebAssembly.Modulequi peut ensuite être instancié..bin: exporte unArrayBufferdu 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.
// Importer le module WebAssembly
import mod from '../util/add.wasm';
// Instancier d'abord pour l'utiliser
const addModule: any = new WebAssembly.Instance(mod);
export async function GET(context) {
const a = Number.parseInt(context.params.a);
const b = Number.parseInt(context.params.b);
return new Response(`${addModule.exports.add(a, b)}`);
}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.
Cloudflare 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:*'.
export const prerender = false;
import { Buffer } from 'node:buffer';Vous devrez également modifier la configuration vite dans votre astro config pour autoriser la syntaxe d'importation node:* :
import {defineConfig} from "astro/config";
import cloudflare from '@astrojs/cloudflare';
export default defineConfig({
adapter: cloudflare({}),
output: 'server',
vite: {
ssr: {
external: ['node:buffer'],
},
},
})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.
:::note[Implications de la compatibilité des paquets]
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.
:::
Pour utiliser wrangler afin d'exécuter votre application localement, mettez à jour le script de prévisualisation :
"preview": "wrangler pages dev ./dist"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é.
Actuellement, 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.
export default defineConfig({
adapter: cloudflare(),
output: 'server',
vite: {
build: {
minify: false,
},
},
});