Documentazione

Risoluzione dei problemi di errore delle pipeline front-end in AEM as a Cloud Service

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

Quando si converte una pipeline full stack in una pipeline front-end (FE) solo in AEM as a Cloud Service, si potrebbero verificare errori di build dovuti a dipendenze specifiche della piattaforma e a requisiti di linting rigidi. La generazione di package-lock.json su Windows o macOS può causare incompatibilità con Cloud Manager basato su Linux. Inoltre, le pipeline FE applicano controlli in stile codice non presenti nelle build Maven full stack.

Note

  • Quando Cloud Manager esegue una pipeline front-end, non esegue prima l’installazione npm, ma semplicemente prende package-lock.json che si trova in Git ed esegue npm audit --production --audit-level=critical. Tuttavia, una pipeline full stack installa le versioni Node/NPM richieste tramite il front-end-maven-plugin, esegue l’installazione npm, pertanto il problema non viene visualizzato nella pipeline full stack.

Descrizione description

Ambiente

  • Prodotto: AEM as a Cloud Service - Sites
  • Pipeline: pipeline solo front-end (FE) tramite Cloud Manager
  • Versione del nodo: 14.19.1
  • npm versione: 6.14.x
  • Sistema operativo per le build locali: Windows (locale), Linux (contenitore Cloud Manager)
  • Autorizzazioni richieste: ruolo Responsabile della distribuzione in Cloud Manager

Problema/Sintomi

  • La pipeline non riesce durante l’installazione npm con errori quali * fsevents non accessibili da chokida r*
  • Errori relativi a package-lock.json file mancanti o non corrispondenti
  • Le build locali hanno esito positivo in Windows o Mac, ma non riescono nella pipeline di Cloud Manager
  • Centinaia di errori ESLint/code-style causano errori di pipeline solo FE, mentre le pipeline full stack non applicano questi controlli per impostazione predefinita

Risoluzione resolution

Per risolvere il problema, effettua le seguenti operazioni:

  1. Assicurarsi che package-lock.json esista nel modulo ui.frontend e che venga eseguito il commit nell'archivio.

  2. Rigenerare package-lock.json e node_modules utilizzando un ambiente Linux (utilizzare Sottosistema Windows per Linux o Docker). Per riprodurre e risolvere i problemi di dipendenza specifici della piattaforma per le pipeline solo FE, utilizzare i seguenti comandi in un terminale WSL:  

    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"

     
    Oppure esegui in un contenitore Linux:
     

    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. Aggiornare le dipendenze obsolete tra cui Jest, Storybook e Webpack.

  4. Utilizzare npm audit con flag di livello di controllo critico e di produzione per identificare i problemi di dipendenza rimanenti. Ad esempio: npm audit --production --audit-level=critical

  5. Eseguire il commit del file package-lock.json rigenerato dall'ambiente Linux all'archivio.

  6. Effettua il push delle modifiche al ramo utilizzato dalla pipeline solo FE.

  7. Eseguire nuovamente la pipeline FE-only in Cloud Manager.

  8. Risolvi eventuali errori ESLint/di tipo codice segnalati durante il processo di compilazione; per una corretta distribuzione, è necessario risolvere tutti gli errori di collegamento.

  9. Se necessario solo a scopo di convalida, rimuovere temporaneamente il linting dallo script di compilazione in package.json. Tuttavia, questo non è raccomandato per l’uso in produzione.

  10. Verifica che la fase di build venga completata senza errori di dipendenza o di puntamento.

  11. Se la distribuzione ha esito positivo ma gli stili e gli script del sito non vengono caricati, controlla le impostazioni di Dispatcher e la configurazione CDN. Verificare che il vhost abilitato includa ServerAlias corretto per il dominio statico. Per i passaggi, consulta La distribuzione della pipeline front-end interrompe il sito Web.

  12. Se la pipeline non riesce con BUILD_NPM_AUDIT_ERROR, rimuovere eventuali nodi SiteConfig o HtmlPageItemsConfig in conflitto. Per i passaggi, consulta Come risolvere BUILD_NPM_AUDIT_ERROR nella pipeline front-end di AEM as a Cloud Service.

Note

  • La pipeline solo FE applica controlli di stile del codice più rigorosi rispetto alle build Maven full stack; tutti gli errori di collegamento devono essere risolti prima della distribuzione.

  • È possibile automatizzare il processo di correzione degli errori di JavaScript e CSS linting aggiungendo lo script seguente a package.json:

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

Questo consente di eseguire npm run lint:fix per correggere automaticamente molti problemi di linting prima di inviare le modifiche.

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