Incohérence de nœud lors de l'hydratation

Cette erreur signifie que, pendant le processus d'hydratation, Angular attendait une structure DOM telle que rendue et annotée lors du rendu côté serveur. Or, côté client, l'arbre DOM était différent de l'arbre DOM rendu par le serveur.

Cette erreur survient généralement à cause d'une manipulation directe du DOM avec des API natives du navigateur qui modifient la structure du DOM en dehors de ce qu'Angular a produit. Elle se produit aussi si vous utilisez innerHTML ou outerHTML pour définir du contenu HTML, ce qui modifie de la même façon la structure du DOM en dehors de ce qu'Angular a produit. Vous pouvez la résoudre en refactorisant le composant pour qu'il utilise les API d'Angular plutôt que les API natives. Si ce n'est pas possible, vous pouvez ajouter l'attribut ngSkipHydration au nœud host de votre composant, ce qui désactive l'hydratation pour le composant et ses enfants. ngSkipHydration ne doit être utilisé qu'en dernier recours et doit être considéré comme un bug à corriger.

Vous trouverez plus d'informations sur l'hydratation dans ce guide.

L'exemple suivant déclenche l'erreur.

@Component({
  selector: 'app-example',
  template: '<div><span>world</span></div>',
})
export class Example {
  hostElement = inject(ElementRef).nativeElement;

  ngOnInit() {
    // Create a new <p> element with the `Hello` text inside
    const newNode = document.createElement('p');
    newNode.innerHTML = 'Hello';

    // Insert the <p> before the first element. Since Angular has no information
    // about the <p> element, it will be looking for the <div> element at the first
    // element position instead. As a result, a hydration mismatch error would be
    // thrown. Instead, update component's template to create the <p> element.
    this.hostElement.insertBefore(newNode, this.hostElement.firstChild);
  }
}

Déboguer l'erreur

Le message d'erreur dans la console du développeur devrait contenir des informations sur la partie précise de la structure DOM de l'application qui pose problème. Examinez cette partie de l'application à la recherche d'erreurs liées à l'hydratation, comme une manipulation directe du DOM avec des API natives.

Vérifiez que votre template a une structure HTML valide. Pour en savoir plus, consultez le guide de l'hydratation.

Vous pouvez ajouter l'attribut ngSkipHydration au nœud host de votre composant comme solution de contournement possible.

Si votre application fonctionne en environnement de développement mais que vous voyez des erreurs d'hydratation dans les builds de production, assurez-vous que le HTML généré qui est livré au navigateur contient les nœuds de commentaire produits par Angular lors du rendu sur le serveur. Ces nœuds de commentaire servent d'ancres au runtime d'Angular pour les view containers (avec ou sans hydratation), et le processus d'hydratation s'attend à les trouver à leur emplacement d'origine. Si vous avez une logique personnalisée qui supprime les nœuds de commentaire du HTML généré par le rendu côté serveur, ou si vous avez configuré votre CDN pour les supprimer avant de servir le contenu, désactivez cette suppression des nœuds de commentaire et vérifiez si les erreurs d'hydratation disparaissent.