Dépannage

Astro fournit plusieurs outils différents pour vous aider à dépanner et à déboguer votre code.

Trucs et astuces

Débogage avec `console.log()`

console.log() est un moyen simple, mais populaire de déboguer votre code Astro. Lorsque vous écrivez votre appel à console.log(), il déterminera où votre sortie de débogage sera affichée.

---
console.log('Salut ! Je suis le serveur. Ceci est affiché dans le terminal où Astro est exécuté.');
---

<script>
console.log('Salut ! Je suis le client. Ceci est affiché dans la console de développement du navigateur.');
</script>

Un appel à console.log() dans le frontmatter d’Astro sera toujours affiché dans le terminal qui exécute le processus d’Astro. Car Astro s’exécute sur le serveur, et jamais dans le navigateur.

Le code qui est écrit ou importé dans un <script> d’Astro sera exécuté dans le navigateur. Toutes les sorties de débogage ou autres appels à console.log() seront affichés dans votre navigateur.

Débogage des composants de framework

Les composants de framework (comme React et Svelte) sont uniques : ils sont rendus sur le serveur par défaut, ce qui signifie que les sorties de débogage seront visibles dans le terminal. Cependant, ils peuvent également être hydratés pour le navigateur, ce qui peut aussi entraîner que vos logs de débogage apparaissent également dans le navigateur.

Cela peut être utile pour déboguer les différences entre la sortie serveur et les composants hydratés dans le navigateur.

Le composant `<Debug />` d’Astro

Pour vous aider à déboguer vos composants Astro, Astro propose un composant <Debug /> qui affiche directement une valeur dans votre template HTML de composant.

Ce composant permet d’inspecter des valeurs du côté client, sans JavaScript. Il peut être utile pour un débogage rapide dans le navigateur, sans avoir à passer d’un terminal à l’autre.

---
import { Debug } from 'astro/components';
const sum = (a, b) => a + b;
---

<!-- Exemple : Affiche {answer: 6} dans le navigateur -->
<Debug answer={sum(2, 4)} />

Le composant Debug prend en charge une variété d’options syntaxiques pour un débogage encore plus souple et concis :

---
import { Debug } from 'astro/components';
const sum = (a, b) => a + b;
const answer = sum(2, 4);
---
<!-- Exemple : Les trois exemples sont équivalents. -->
<Debug answer={sum(2, 4)} />
<Debug {{answer: sum(2, 4)}} />
<Debug {answer} />

Messages d’erreur courants

Voici quelques messages d’erreur courants que vous pourriez rencontrer dans le terminal, leur signification et la marche à suivre. Consultez notre guide de référence complet pour obtenir la liste complète des erreurs d’Astro que vous pourriez rencontrer.

Cannot use import statement outside a module

Dans les composants Astro, les balises <script> sont chargées comme des modules JavaScript par défaut. Si vous avez ajouté la directive is:inline ou n’importe quel autre attribut à votre balise, ce comportement par défaut est désactivé.

Solution : Si vous avez ajouté n’importe quel attribut à votre balise <script>, vous devez aussi ajouter la directive type="module" pour pouvoir utiliser les importations.

Statut : Comportement attendu d’Astro, intentionnel.

Vous n’êtes pas sûr qu’il s’agisse de votre problème ? Vérifiez si quelqu’un d’autre a déjà signalé ce type d’erreur !

`document` (or `window`) is not defined

Cette erreur se produit lorsque vous essayez d’accéder à document ou window sur le serveur.

Les composants Astro fonctionnent sur le serveur, vous ne pouvez donc pas accéder à ces objets spécifiques au navigateur dans le frontmatter.

Les composants de framework s’exécutent par défaut sur le serveur, et cette erreur peut donc se produire lors de l’accès à document ou window pendant le rendu.

Solution : Déterminez le code qui appelle document ou window. Si vous n’utilisez pas directement document ou window et que vous obtenez toujours cette erreur, vérifiez si les paquets que vous importez sont destinés à fonctionner sur le client.

Si le code se trouve dans un composant Astro, déplacez-le dans une balise <script> à l’extérieur du frontmatter. Cela indique à Astro d’exécuter ce code sur le client, où document et window sont disponibles.
Si le code est dans un composant de framework, essayez d’accéder à ces objets après le rendu en utilisant des méthodes de cycle de vie (par exemple useEffect() dans React, onMounted() dans Vue, et onMount() dans Svelte). Indiquez au composant du framework de s’hydrater côté client en utilisant une directive client, comme client:load, pour exécuter ces méthodes de cycle de vie. Vous pouvez également empêcher le composant d’effectuer un rendu sur le serveur en ajoutant la directive client:only.

Statut : Comportement attendu d’Astro, intentionnel.

Expected a default export

Cette erreur peut survenir lorsque vous essayez d’importer ou de restituer un composant invalide ou qui ne fonctionne pas correctement. (Ce message d’erreur apparaît en raison de la manière dont fonctionne l’importation de composants UI dans Astro.)

Solution : Essayez de trouver des erreurs dans les composants que vous importez et affichez et assurez-vous qu’ils fonctionnent correctement. Envisagez d’ouvrir l’un des modèles de démarrage d’Astro depuis astro.new et de dépanner uniquement votre composant dans un projet Astro minimal.

Statut : Comportement attendu par Astro, intentionnel.

Refused to execute inline script

Il se peut que l’erreur suivante apparaisse dans la console du navigateur :

Refused to execute inline script because it violates the following Content Security Policy directive: …

Cela signifie que la politique de sécurité du contenu (CSP) de votre site interdit l’exécution des balises <script> incorporées à la page, qu’Astro génère par défaut.

Solution : Mettez à jour votre CSP pour inclure script-src: 'unsafe-inline' afin d’autoriser l’exécution des scripts incorporés à la page. Vous pouvez également utiliser une intégration tierce telle que astro-shield pour générer les en-têtes CSP pour vous.

Problèmes courants

Mon composant ne s’affiche pas

En premier lieu, vérifiez que vous avez importé le composant dans le script de votre composant .astro ou dans votre fichier .mdx.

Ensuite, vérifiez votre instruction d’importation :

Votre importation dirige-t-elle vers le bon endroit ? (Vérifiez votre chemin d’importation.)
Votre importation a-t-elle le même nom que le composant importé ? (Vérifiez le nom de votre composant et qu’il respecte la syntaxe .astro.)
Avez-vous inclus l’extension dans l’importation ? (Vérifiez que votre fichier importé contient une extension, par exemple .astro, .md, .vue, .svelte. À noter : Les extensions de fichiers sont optionnelles pour les fichiers .js(x) et .ts(x)).

Mon composant n’est pas interactif

Si votre composant est affiché (voir la précédente section) mais ne répond pas à l’interaction utilisateur, alors vous avez peut-être oublié une directive client:* pour hydrater votre composant.

Par défaut, un composant UI de framework n’est pas hydraté sur le navigateur. Si aucune directive client:* n’est fournie, son HTML est rendu sur la page sans JavaScript.

Cannot find package ‘X’

Si vous voyez un avertissement du type "Cannot find package 'react'" (ou similaire) lorsque vous démarrez Astro, cela signifie que vous devez installer ce paquet dans votre projet. Tous les gestionnaires de paquets n’installent pas automatiquement les dépendances pour vous. Si vous êtes sur Node v16+ et que vous utilisez npm, vous ne devriez pas avoir à vous soucier de cette section.

React, par exemple, est une dépendance peer de l’intégration @astrojs/react. Cela signifie que vous devez installer les paquets officiels react et react-dom avec votre intégration. L’intégration s’appuiera alors automatiquement sur ces paquets.

# Exemple : Installer les intégrations et les frameworks ensemble
npm install @astrojs/react react-dom

Voir le guide des intégrations d’Astro pour des instructions sur l’ajout de moteurs de rendu de frameworks, d’outils CSS et d’autres paquets à Astro.

Utilisation d’Astro avec Yarn 2+ (Berry)

Yarn 2+, alias Berry, utilise une technique appelée « Plug’n’Play » (PnP) pour stocker et gérer les modules Node, qui peut causer des problèmes lors de l’initialisation d’un nouveau projet Astro en utilisant create-astro ou pendant que vous travaillez avec Astro. Une solution est de définir la propriété nodeLinker dans yarnrc.yml à la valeur node-modules :

nodeLinker: "node-modules"

Ajouter des dépendances à Astro dans un monorepo

Lorsque vous travaillez avec Astro dans une configuration monorepo, les dépendances du projet doivent être ajoutées dans le fichier package.json de chaque projet.

Cependant, vous pouvez aussi vouloir utiliser Astro à la racine du monorepo (par exemple, les projets Nx recommandent d’installer les dépendances à la racine). Dans ce cas, ajoutez manuellement les dépendances liées à Astro (par exemple @astrojs/vue, astro-component-lib) à la partie vite.ssr.noExternal de la configuration d’Astro pour vous assurer que ces dépendances sont correctement installées et regroupées :

import { defineConfig } from 'astro/config'
export default defineConfig({
  vite: {
    ssr: {
      noExternal: [
        '@astrojs/vue',
        'astro-component-lib',
      ]
    }
  }
})

Utilisation de `<head>` dans un composant

Dans Astro, l’utilisation d’une balise <head> fonctionne comme n’importe quelle autre balise HTML : elle n’est pas déplacée en haut de la page ou fusionnée avec la balise <head> existante. Pour cette raison, vous ne voulez généralement inclure qu’une seule balise <head> dans une page. Nous recommandons d’écrire cet unique <head> et son contenu dans un composant de mise en page.

Un `<style>` inattendu est inclus

Vous remarquerez peut-être que la balise <style> d’un composant importé est incluse dans votre source HTML même si ce composant n’apparaît pas dans la sortie finale. Par exemple, cela se produira avec les composants rendus conditionnellement qui ne sont pas affichés.

Le processus de compilation d’Astro fonctionne sur le graphe des modules : une fois qu’un composant est inclus dans le modèle, sa balise <style> est traitée, optimisée et regroupée, qu’elle apparaisse ou non dans la sortie finale.

Échapper les caractères spéciaux dans Markdown

Certains caractères ont une signification particulière dans Markdown. Vous devrez peut-être utiliser une syntaxe différente si vous souhaitez les afficher. Pour ce faire, vous pouvez utiliser des entités HTML pour ces caractères.

Par exemple, pour éviter que < soit interprété comme le début d’un élément HTML, écrivez <.

Créer des reproductions minimales

Lorsque vous dépannez votre code, il peut être utile de créer une reproduction minimale du problème que vous pouvez partager. Il s’agit d’un projet Astro plus petit et simplifié qui démontre votre problème. Le fait d’avoir une reproduction fonctionnelle dans un nouveau projet permet de confirmer qu’il s’agit d’un problème reproductible et qu’il n’est pas dû à quelque chose d’autre dans votre environnement personnel ou dans un projet existant.

Le partage d’une reproduction minimale est utile lorsque vous demandez de l’aide dans nos fils d’assistance et est souvent nécessaire lorsque vous déposez un rapport de bogue auprès d’Astro.

Créer un StackBlitz via astro.new

Vous pouvez utiliser astro.new pour créer un nouveau projet Astro en un seul clic. Pour des reproductions minimales, nous recommandons fortement de partir de l’exemple minimal (vide) exécuté dans StackBlitz, avec le moins de code supplémentaire possible.

StackBlitz exécutera ce projet Astro dans le navigateur, en dehors de votre environnement local. Il vous fournira également un lien partageable afin que n’importe quel mainteneur d’Astro ou membre de l’équipe d’assistance puisse voir votre reproduction minimale en dehors de leur propre environnement local. Cela signifie que tout le monde voit exactement le même projet, avec la même configuration et les mêmes dépendances. Il est ainsi plus facile pour quelqu’un d’autre d’aider à dépanner votre code. Si le problème est reproductible, cela vous permet de vérifier que le problème se trouve dans le code d’Astro lui-même et vous pouvez soumettre un rapport de bogue en toute confiance.

Notez que tous les problèmes ne sont pas reproductibles dans StackBlitz. Par exemple, votre problème peut dépendre d’un environnement spécifique ou d’un gestionnaire de paquets, ou il peut impliquer le streaming HTML, qui n’est pas pris en charge par StackBlitz. Dans ce cas, créez un nouveau projet Astro minimal (vide) en utilisant la CLI, reproduisez le problème et téléchargez-le sur un dépôt GitHub. Au lieu de partager une URL StackBlitz, fournissez un lien vers le dépôt GitHub de votre reproduction minimale.

Code minimal

Une fois que votre projet vide est mis en place, passez par les étapes pour reproduire le problème. Cela peut inclure l’ajout de paquets, la modification de la configuration et l’écriture de code.

Vous ne devez ajouter que le minimum de code nécessaire pour reproduire le problème. Ne reproduisez pas d’autres éléments de votre projet existant et supprimez tout le code qui n’est pas directement lié au problème.

Créer un ticket

Si votre problème peut être reproduit, il est temps de créer un ticket et de déposer un rapport de bug !

Allez sur le dépôt Astro approprié sur GitHub et ouvrez un nouveau ticket (« Issue » dans l’interface). La plupart des dépôts disposent d’un modèle de ticket qui posera des questions ou demandera des informations pour pouvoir l’envoyer. Il est important que vous suiviez ces modèles car si vous ne fournissez pas les informations dont nous avons besoin, nous devrons vous les demander… et personne ne travaillera sur votre problème !

Incluez le lien vers votre reproduction minimale sur StackBlitz (ou le dépôt GitHub, si nécessaire). Commencez par une description du comportement attendu par rapport au comportement réel pour fournir le contexte du problème. Ensuite, incluez des instructions claires, étape par étape, sur la façon de reproduire le problème dans un projet Astro.

Besoin de plus ?

Venez discuter avec nous sur Discord et expliquez votre problème dans le salon #support. Nous sommes toujours heureux de pouvoir vous aider !

Visitez les tickets actuellement ouverts dans Astro pour voir si vous rencontrez un problème connu ou soumettre un rapport de bug.

Vous pouvez aussi visiter les discussions RFC pour voir si vous avez trouvé une limitation connue d’Astro et vérifier s’il existe actuellement des propositions liées à votre utilisation.

Contribuer Communauté Parrainer