DokumentationExperience Cloud KCS

Unterstützung der Node.js- und npm-Version und Kompatibilität für AEM-Frontend-Builds

Letzte Aktualisierung: 7. Juli 2026

AEM-Frontend-Module (z. B. ui.frontend mit React oder Webpack) erfordern eine Node.js-Version, die mit der AEM-Build-Umgebung kompatibel ist, und die Verwendung einer nicht unterstützten oder nicht übereinstimmenden Version führt zu Fehlern bei der Cloud Manager-Pipeline-Erstellung oder Unsicherheit beim Upgrade. Um das Problem zu beheben, identifizieren Sie Ihr Bereitstellungsmodell, bestätigen Sie, dass Ihre Node.js- und npm-Zielversionen unterstützt werden, und legen Sie in Ihrer Pipeline-Konfiguration die richtige Version fest.

Beschreibung description

Umgebung

  • Adobe Experience Manager as a Cloud Service
  • AEM Managed Services (AEM 6.5)
  • Adobe Experience Manager 6.5 (On-Premise)

Problem/Symptome

  • Cloud Manager-Pipeline-Builds schlagen fehl, wenn eine nicht unterstützte Node.js-Version verwendet wird (z. B. bei Verwendung von Node 20, bevor Unterstützung hinzugefügt wurde).
  • Unsicherheit darüber, welche npm-Version mit einer unterstützten Node.js-Version gebündelt ist (z. B. npm 10.8.2 mit Node 18 oder npm 9.6.7 mit Node 23.11.1).

Ursache

Verschiedene AEM-Bereitstellungsmodelle behandeln Node.js unterschiedlich. In AEM as a Cloud Service ist Node.js Teil des Cloud Manager-Build-Containers mit validierten Versionen. In AEM 6.5 Managed Services oder On-Premise ist Node.js eine reine Build-Time-Abhängigkeit, die von Ihnen verwaltet wird, und es gibt keine offizielle Unterstützungsmatrix. Der Versuch, Versionen zu verwenden, die noch nicht in Cloud Manager veröffentlicht wurden, oder nicht übereinstimmende npm-Versionen können zu Build-Inkompatibilitäten führen.

Schritte zur Reproduktion

  1. Identifizieren Sie Ihr Bereitstellungsmodell: AEM as a Cloud Service, AEM 6.5 Managed Services oder AEM 6.5 On-Premise.
  2. Führen Sie für AEM as a Cloud Service node -v und npm -v in einem Pipeline-Build-Schritt aus und überprüfen Sie die gedruckten Versionen in den Build-Protokollen.
  3. Vergleichen Sie Ihre Node.js-Zielversion mit der Liste der offiziell unterstützten Versionen.

Lösung resolution

Um das Problem zu beheben, identifizieren Sie Ihr AEM-Bereitstellungsmodell und führen Sie dann die Schritte für Ihre Umgebung aus:

Für AEM as a Cloud Service

  1. Stellen Sie sicher, dass Ihre Node.js-Zielversion unterstützt wird. Gemäß der offiziellen Dokumentation werden die Hauptversionen 12, 14, 16, 18, 20, 22 und 23 unterstützt. Vergleichen Sie dies mit der Liste der von Experience League unterstützten Konfigurationen.
  2. Bestätigen Sie die npm-Version, die mit Ihrer Node.js-Version gebündelt ist. Führen Sie node -v und npm -v in einem Cloud Manager-Pipeline-Build-Schritt aus und überprüfen Sie die Protokolle (z. B. Node 18-Pakete npm 10.8.2 und Node 23.11.1-Pakete npm 9.6.7). Wenn npm eine 404-Version für seine Version meldet, die Unterschiede in der öffentlichen Registrierung widerspiegelt, bestätigen Sie also die tatsächliche gebündelte Version.
  3. Konfigurieren Sie die Node.js-Version in Ihrer Pipeline. Wechseln Sie in Cloud Manager zu Umgebungen > Konfiguration > Umgebungsvariablen und legen Sie CM_CUSTOM_VAR_NODE_VERSION (oder NODE_VERSION fest. Führen Sie die Pipeline erneut aus und bestätigen Sie die Knotenversion in den Protokollen, um sicherzustellen, dass in pom.xml oder Ihrem Build-Skript keine kollidierende Version definiert ist.
  4. Legen Sie für Full-Stack-Pipelines NODE_VERSION auf 20 fest, um Node.js 20 zu verwenden, und überprüfen Sie Ihre Projektabhängigkeiten auf Kompatibilität mit Node 20.
  5. Verwenden Sie Node.js 22 oder 23 nur, wenn dokumentierte Unterstützung vorhanden ist. Wenn ein Frontend-Build fehlschlägt, kehren Sie zu Knoten 18 oder 20 zurück und testen Sie die Kompatibilität der Abhängigkeiten.
  6. Überprüfen Sie die Kompatibilität von Drittanbieterabhängigkeiten, indem Sie Builds mit der neuen Node.js-Version testen und keine Frontend-Regressionen bestätigen. Wenden Sie sich bei herstellerspezifischen Problemen direkt an den Drittanbieter, da Adobe seine Kompatibilitätsdetails nicht angeben kann.
  7. Bestätigen Sie die Fehlerbehebung, indem Sie node -v und npm -v in den Build-Protokollen ausführen und eine vollständige Pipeline-Ausführung auslösen, um zu überprüfen, ob der ui.frontend Build erfolgreich ist, ohne dass Fehler wegen nicht übereinstimmender Versionen auftreten.
  8. Wenn Builds trotz korrekter Konfiguration immer noch fehlschlagen, wenden Sie sich mit Ihren Pipeline-Protokollen, pom.xml, package.json und der Cloud Manager-Umgebungsvariablenliste an den Adobe-Support.

Für AEM 6.5 (Managed Services und On-Premise)

  1. Beachten Sie, dass es keine offizielle Node.js-Unterstützungsmatrix für AEM 6.5 gibt. Node.js wird vom Kunden verwaltet, nur für Tools zur Build-Zeit verwendet und von der AEM-Laufzeit entkoppelt.
  2. Halten Sie beim Aktualisieren von Node.js und npm die package.json und pom.xml konsistent, sodass lokale und CI-Builds übereinstimmen (z. B. beim Aktualisieren von Node 12.22.7 auf 16.17.0 und npm 6.14.0 auf 8.15.0).
  3. Bestätigen Sie die Versionen, indem Sie node -v und npm -v lokal und in der CI ausführen, und überprüfen Sie, ob der Frontend-Build abgeschlossen wurde, ohne dass Fehler wegen nicht übereinstimmender Versionen auftreten.
  4. Wenn weiterhin Verwirrung oder Build-Probleme auftreten, wenden Sie sich mit Ihren Build-Skript-Details, -pom.xml und -package.json an den Adobe-Support.

Verwandtes Lesen

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