DocumentationExperience Cloud KCS

Prise en charge et compatibilité des versions de Node.js et npm pour les builds front-end AEM

Dernière mise à jour : 7 juillet 2026

Les modules front-end d’AEM (tels que ui.frontend avec React ou Webpack) nécessitent une version de Node.js compatible avec l’environnement de création d’AEM. L’utilisation d’une version non prise en charge ou incohérente entraîne des échecs de création de pipeline Cloud Manager ou une incertitude lors de la mise à niveau. Pour résoudre ce problème, identifiez votre modèle de déploiement, vérifiez que vos versions Node.js et npm cibles sont prises en charge, puis définissez la version appropriée dans la configuration de votre pipeline.

Description description

Environnement

  • Adobe Experience Manager as a Cloud Service
  • AEM Managed Services (AEM 6.5)
  • Adobe Experience Manager 6.5 (on-premise)

Problème/Symptômes

  • Les versions du pipeline Cloud Manager échouent lors de l’utilisation d’une version de Node.js non prise en charge (par exemple, en utilisant Node 20 avant l’ajout de la prise en charge).
  • Incertitude quant à la version de npm groupée avec une version de Node.js prise en charge (par exemple, npm 10.8.2 avec le nœud 18 ou npm 9.6.7 avec le nœud 23.11.1).

Cause principale

Différents modèles de déploiement d’AEM gèrent Node.js différemment. Dans AEM as a Cloud Service, Node.js fait partie du conteneur de création Cloud Manager avec des versions validées. Dans AEM 6.5 Managed Services ou On-premise, Node.js est une dépendance purement au moment de la création que vous gérez et il n’existe aucune matrice de prise en charge officielle. Toute tentative d’utilisation de versions non encore publiées dans Cloud Manager ou de versions npm incompatibles peut entraîner des incompatibilités de version.

Procédure à suivre

  1. Identifiez votre modèle de déploiement : AEM as a Cloud Service, AEM 6.5 Managed Services ou AEM 6.5 on-premise.
  2. Pour AEM as a Cloud Service, exécutez node -v et npm -v dans une étape de création de pipeline et passez en revue les versions imprimées dans les journaux de création.
  3. Comparez votre version de Node.js cible à la liste des versions officiellement prises en charge.

Résolution resolution

Pour résoudre ce problème, identifiez votre modèle de déploiement AEM, puis suivez les étapes pour votre environnement :

Pour AEM as a Cloud Service

  1. Vérifiez que votre version Node.js cible est prise en charge. Selon la documentation officielle, les versions majeures prises en charge sont 12, 14, 16, 18, 20, 22 et 23. Effectuez une vérification croisée par rapport à la liste des éléments pris en charge par Experience League.
  2. Confirmez la version npm incluse avec votre version de Node.js. Exécutez node -v et npm -v dans une étape de création de pipeline Cloud Manager et examinez les journaux (par exemple, les lots Node 18 npm 10.8.2 et Node 23.11.1 npm 9.6.7). Si npm signale un 404 pour sa version, cela reflète les différences de registre public. Confirmez donc la version réellement groupée.
  3. Configurez la version de Node.js dans votre pipeline. Dans Cloud Manager, accédez à Environnements > Configuration > Variables d’environnement et définissez CM_CUSTOM_VAR_NODE_VERSION (ou NODE_VERSION le cas échéant). Exécutez à nouveau le pipeline et confirmez la version du nœud dans les journaux, en vous assurant qu’aucune version en conflit n’est définie dans pom.xml ou votre script de build.
  4. Pour les pipelines full stack, définissez NODE_VERSION sur 20 pour utiliser Node.js 20 et validez les dépendances de votre projet pour la compatibilité avec Node 20.
  5. Utilisez Node.js 22 ou 23 uniquement lorsqu’il existe une prise en charge documentée. Si une version front-end échoue, revenez au nœud 18 ou 20 et testez la compatibilité des dépendances.
  6. Validez la compatibilité des dépendances tierces en testant les versions avec la nouvelle version de Node.js et en confirmant l’absence de régressions front-end. Pour les problèmes spécifiques au fournisseur, contactez directement le fournisseur tiers, car Adobe ne peut pas fournir ses détails de compatibilité.
  7. Confirmez le correctif en exécutant node -v et npm -v dans les journaux de génération et en déclenchant une exécution complète du pipeline pour vérifier que la build ui.frontend réussit sans erreurs de correspondance de version.
  8. Si les versions échouent toujours malgré une configuration correcte, contactez l’assistance Adobe avec vos journaux de pipeline, pom.xml, package.json et votre liste de variables d’environnement Cloud Manager.

Pour AEM 6.5 (Managed Services et On-premise)

  1. Notez qu’il n’existe pas de matrice de prise en charge officielle de Node.js pour AEM 6.5. Node.js est géré par le client, utilisé uniquement pour l’outil au moment de la création, et découplé de l’exécution d’AEM.
  2. Lors de la mise à jour de Node.js et npm, veillez à ce que package.json et pom.xml soient cohérents afin que les versions locales et CI s’alignent (par exemple, la mise à niveau de Node 12.22.7 vers 16.17.0 et de npm 6.14.0 vers 8.15.0).
  3. Confirmez les versions en exécutant node -v et npm -v localement et dans CI, et vérifiez que la création front-end se termine sans erreurs de correspondance de version.
  4. Si des problèmes de confusion ou de build persistent, contactez l’assistance Adobe en indiquant les détails, les pom.xml et les package.json du script de build.

Lecture connexe

recommendation-more-help
experience-cloud-kcs-help-kbarticles