Dokumentation

Fehlerbehebung bei Frontend-Pipeline-Fehlern in AEM as a Cloud Service

Last update: Tue Nov 25 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

Beim Konvertieren einer Full-Stack-Pipeline in eine Nur-Frontend-Pipeline (FE) in AEM as a Cloud Service können Build-Fehler aufgrund plattformspezifischer Abhängigkeiten und strenger Verknüpfungsanforderungen auftreten. Das Generieren von package-lock.json unter Windows oder macOS kann zu Inkompatibilitäten mit der Linux-basierten Cloud Manager führen. Darüber hinaus erzwingen FE-Pipelines Code-artige Prüfungen, die in Full-Stack-Maven-Builds nicht vorhanden sind.

Hinweise

  • Wenn Cloud Manager eine Frontend-Pipeline ausführt, führt es nicht zuerst die npm-Installation aus, sondern nimmt einfach die in Git enthaltene package-lock.json und führt sie npm audit --production --audit-level=critical aus. Allerdings installiert eine Full-Stack-Pipeline die von uns angeforderten Node/NPM-Versionen über das frontend-maven-plugin. Sie führt jedoch die npm-Installation aus, sodass wir das Problem nicht in der Full-Stack-Pipeline sehen.

Beschreibung description

Umgebung

  • Produkt: AEM as a Cloud Service - Sites
  • Pipeline: Nur Frontend-Pipeline (FE) über Cloud Manager
  • Knotenversion: 14.19.1
  • npm-Version: 6.14.x
  • Betriebssystem für lokale Builds: Windows (lokal), Linux (Cloud Manager-Container)
  • Erforderliche Berechtigungen: Rolle „Bereitstellungs-Manager“ in Cloud Manager

Problem/Symptome

  • Die Pipeline schlägt während der npm-Installation fehl und verursacht Fehler wie * fseevents, auf die von chokida r* nicht zugegriffen werden kann
  • Fehler im Zusammenhang mit fehlenden oder nicht übereinstimmenden package-lock.json
  • Lokale Builds sind unter Windows oder Mac erfolgreich, schlagen jedoch in der Cloud Manager-Pipeline fehl
  • Hunderte von ESLint-/Code-ähnlichen Fehlern verursachen Pipeline-Fehler, die nur FE betreffen, während Full-Stack-Pipelines diese Prüfungen standardmäßig nicht erzwingen

Lösung resolution

Führen Sie zur Behebung des Problems folgende Schritte aus:

  1. Stellen Sie sicher, dass package-lock.json im ui.frontend vorhanden ist und in Ihr Repository übertragen wird.

  2. Generieren Sie package-lock.json und node_modules mithilfe einer Linux-Umgebung (verwenden Sie das Windows-Subsystem für Linux oder Docker). Verwenden Sie die folgenden Befehle in einem WSL-Terminal, um plattformspezifische Abhängigkeitsprobleme für reine FE-Pipelines zu reproduzieren und zu beheben:  

    code language-none 
    cd /path/to/your/project
rm -rf package-lock.json node_modules
npm install
git add package-lock.json
git commit -m "Regenerate package-lock.json on Linux"

     
    Oder in einem Linux-Container ausführen:
     

    code language-none 
    docker run --rm -v $(pwd):/app -w /app node:16-alpine \
  sh -c "rm -rf node_modules package-lock.json && npm install"

     

  3. Aktualisieren Sie veraltete Abhängigkeiten einschließlich Jest, Storybook und Webpack.

  4. Verwenden Sie npm audit mit Flags für Produktions- und kritische Audit-Ebene, um verbleibende Abhängigkeitsprobleme zu identifizieren. Beispiel: npm audit --production --audit-level=critical

  5. Übertragen Sie die neu generierte package-lock.json-Datei aus der Linux-Umgebung in Ihr Repository.

  6. Änderungen an die Verzweigung pushen, die von der reinen FE-Pipeline verwendet wird.

  7. Führen Sie die Nur-FE-Pipeline in Cloud Manager erneut aus.

  8. Beheben Sie alle ESLint-/Code-ähnlichen Fehler, die während des Build-Prozesses gemeldet wurden. Alle Link-Fehler müssen für eine erfolgreiche Bereitstellung behoben werden.

  9. Wenn dies nur zu Validierungszwecken erforderlich ist, entfernen Sie in package.json vorübergehend den Link aus dem Build-Skript . Dies wird jedoch für die Verwendung in der Produktion nicht empfohlen.

  10. Vergewissern Sie sich, dass der Build-Schritt ohne Abhängigkeiten oder Verknüpfungsfehler erfolgreich abgeschlossen wurde.

  11. Wenn die Bereitstellung erfolgreich ist, die Stile und Skripte Ihrer Site jedoch nicht geladen werden, überprüfen Sie die Dispatcher-Einstellungen und die CDN-Konfiguration. Stellen Sie sicher, dass Ihr aktivierter vhost die richtige ServerAlias für die statische Domain enthält. Anweisungen hierzu finden Sie unter Frontend-Pipeline-Bereitstellung unterbricht die Website.

  12. Wenn die Pipeline mit BUILD_NPM_AUDIT_ERROR fehlschlägt, entfernen Sie alle widersprüchlichen SiteConfig- oder HtmlPageItemsConfig-Knoten. Anweisungen hierzu finden Sie Wie Sie BUILD_NPM_AUDIT_ERROR in der AEM as a Cloud Service-Frontend-Pipeline beheben.

Hinweise

  • Die reine FE-Pipeline erzwingt strengere Code-Stilprüfungen als Full-Stack-Maven-Builds. Alle Link-Fehler müssen vor der Bereitstellung behoben werden.

  • Sie können den Prozess der Behebung von JavaScript- und CSS-Verknüpfungsfehlern automatisieren, indem Sie das folgende Skript zu Ihrem package.json hinzufügen:

    code language-none 
    "scripts": {
  "lint:fix": "npm run lint:js:fix && npm run lint:css:fix"
}

Auf diese Weise können Sie npm run lint:fix ausführen, um viele Verknüpfungsprobleme automatisch zu korrigieren, bevor Sie Änderungen per Push übertragen.

recommendation-more-help
3d58f420-19b5-47a0-a122-5c9dab55ec7f