DocumentazioneExperience Cloud KCS

Supporto delle versioni Node.js e npm e compatibilità per le build front-end di AEM

Ultimo aggiornamento: 7 luglio 2026

I moduli front-end di AEM (ad esempio ui.frontend con React o Webpack) richiedono una versione di Node.js compatibile con l’ambiente di build AEM e l’utilizzo di una versione non supportata o non corrispondente causa errori o incertezze di build della pipeline di Cloud Manager durante l’aggiornamento. Per risolvere il problema, identifica il modello di distribuzione, conferma che le versioni di Node.js e npm di destinazione siano supportate e imposta la versione corretta nella configurazione della pipeline.

Descrizione description

Ambiente

  • Adobe Experience Manager as a Cloud Service
  • AEM Managed Services (AEM 6.5)
  • Adobe Experience Manager 6.5 (locale)

Problema/Sintomi

  • Le build della pipeline di Cloud Manager non riescono quando si utilizza una versione di Node.js non supportata (ad esempio, utilizzando Node 20 prima dell’aggiunta del supporto).
  • Incertezza su quale versione npm è inclusa con una versione di Node.js supportata (ad esempio, npm 10.8.2 con Nodo 18 o npm 9.6.7 con Nodo 23.11.1).

Causa principale

Diversi modelli di distribuzione di AEM gestiscono Node.js in modo diverso. In AEM as a Cloud Service, Node.js fa parte del contenitore di build Cloud Manager con versioni convalidate. In AEM 6.5 Managed Services o on-premise, Node.js è puramente una dipendenza build-time che gestisci e non esiste una matrice di supporto ufficiale. Il tentativo di utilizzare versioni non ancora rilasciate in Cloud Manager o versioni npm non corrispondenti può causare incompatibilità di build.

Passaggi per riprodurre l’errore

  1. Identifica il modello di implementazione: AEM as a Cloud Service, AEM 6.5 Managed Services o AEM 6.5 on-premise.
  2. Per AEM as a Cloud Service, esegui node -v e npm -v in un passaggio di build della pipeline e controlla le versioni stampate nei registri di build.
  3. Confronta la versione di Node.js di destinazione con l’elenco delle versioni ufficialmente supportate.

Risoluzione resolution

Per risolvere il problema, identifica il modello di distribuzione di AEM, quindi segui i passaggi per il tuo ambiente:

Per AEM as a Cloud Service

  1. Verifica che la versione di Node.js di destinazione sia supportata. Secondo la documentazione ufficiale, le versioni principali supportate sono 12, 14, 16, 18, 20, 22 e 23. Verifica incrociata con l’elenco supportato da Experience League.
  2. Conferma la versione npm in bundle con la versione Node.js. Esegui node -v e npm -v in un passaggio di build della pipeline Cloud Manager e rivedi i registri (ad esempio, bundle Node 18 npm 10.8.2 e bundle Node 23.11.1 npm 9.6.7). Se npm riporta un 404 per la sua versione, che riflette le differenze del registro pubblico, quindi confermare la versione effettiva nel bundle.
  3. Configura la versione di Node.js nella pipeline. In Cloud Manager, vai a Ambienti > Configurazione > Variabili di ambiente e imposta CM_CUSTOM_VAR_NODE_VERSION (o NODE_VERSION se applicabile). Eseguire nuovamente la pipeline e confermare la versione del nodo nei registri, assicurandosi che non siano definite versioni in conflitto in pom.xml o nello script di compilazione.
  4. Per le pipeline full stack, imposta NODE_VERSION su 20 per utilizzare Node.js 20 e convalida le dipendenze del progetto per la compatibilità con Node 20.
  5. Utilizza Node.js 22 o 23 solo in presenza di supporto documentato. Se una build front-end non riesce, ripristina il nodo 18 o 20 e verifica la compatibilità della dipendenza.
  6. Convalida la compatibilità delle dipendenze di terze parti testando le build con la nuova versione di Node.js e confermando l’assenza di regressioni front-end. Per problemi specifici del fornitore, contatta direttamente il fornitore di terze parti, poiché Adobe non può fornire i relativi dettagli di compatibilità.
  7. Confermare la correzione eseguendo node -v e npm -v nei registri di compilazione e attivando un’esecuzione completa della pipeline per verificare che la compilazione ui.frontend abbia esito positivo senza errori di mancata corrispondenza delle versioni.
  8. Se le build non riescono nonostante la configurazione corretta, contatta il supporto Adobe con i registri della pipeline, pom.xml, package.json e l’elenco delle variabili di ambiente Cloud Manager.

Per AEM 6.5 (Managed Services e on-premise)

  1. Nota che non esiste una matrice ufficiale di supporto Node.js per AEM 6.5. Node.js è gestito dal cliente, utilizzato solo per la creazione di strumenti in fase di generazione e scollegato dal runtime di AEM.
  2. Durante l’aggiornamento di Node.js e npm, mantieni coerenti package.json e pom.xml in modo che le build locali e CI siano allineate (ad esempio, l’aggiornamento di Node 12.22.7 a 16.17.0 e npm 6.14.0 a 8.15.0).
  3. Confermare le versioni eseguendo node -v e npm -v localmente e in CI, quindi verificare che la build front-end venga completata senza errori di mancata corrispondenza delle versioni.
  4. In caso di confusione o problemi di compilazione, contatta il supporto Adobe con i dettagli dello script di compilazione, pom.xml e package.json.

Lettura correlata

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