DocumentaçãoKCS da Experience Cloud

Compatibilidade e suporte à versão de Node.js e npm para builds de front-end do AEM

Última atualização: 7 de julho de 2026

Os módulos de front-end do AEM (como ui.frontend com o React ou Webpack) exigem uma versão do Node.js compatível com o ambiente de compilação do AEM, e o uso de uma versão sem suporte ou incompatível resulta em falhas ou incerteza na compilação de pipeline do Cloud Manager ao atualizar. Para corrigir o problema, identifique o modelo de implantação, confirme se as versões Node.js e npm de destino são compatíveis e defina a versão correta na configuração do pipeline.

Descrição description

Ambiente

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

Problema/Sintomas

  • As builds de pipeline do Cloud Manager falham ao usar uma versão Node.js não compatível (por exemplo, usar o Nó 20 antes de o suporte ser adicionado).
  • Incerteza sobre qual versão de npm é fornecida com uma versão Node.js compatível (por exemplo, npm 10.8.2 com Node 18 ou npm 9.6.7 com Node 23.11.1).

Causa raiz

Modelos diferentes de implantação do AEM lidam com Node.js de forma diferente. No AEM as a Cloud Service, o Node.js faz parte do contêiner de compilação do Cloud Manager com versões validadas. No AEM 6.5 Managed Services ou no local, o Node.js é puramente uma dependência de tempo de criação gerenciada por você e não existe nenhuma matriz de suporte oficial. Tentar usar versões ainda não lançadas no Cloud Manager ou versões npm incompatíveis pode causar incompatibilidades de build.

Etapas a serem reproduzidas

  1. Identifique o modelo de implantação: AEM as a Cloud Service, AEM 6.5 Managed Services ou AEM 6.5 no local.
  2. Para o AEM as a Cloud Service, execute o node -v e o npm -v em uma etapa de compilação de pipeline e revise as versões impressas nos logs de compilação.
  3. Compare sua versão do Node.js de destino com a lista de versões oficialmente suportadas.

Resolução resolution

Para corrigir o problema, identifique o modelo de implantação do AEM e siga as etapas para o seu ambiente:

Para AEM as a Cloud Service

  1. Verifique se a versão de destino Node.js é compatível. De acordo com a documentação oficial, as principais versões compatíveis são 12, 14, 16, 18, 20, 22 e 23. Verificação cruzada com a lista de Experience League suportados.
  2. Confirme a versão npm fornecida com a versão Node.js. Execute node -v e npm -v em uma etapa de compilação de pipeline da Cloud Manager e examine os logs (por exemplo, o nó 18 agrupa npm 10.8.2 e o nó 23.11.1 agrupa npm 9.6.7). Se o npm reportar um 404 para sua versão, isso refletirá as diferenças no registro público, confirme a versão agrupada real.
  3. Configure a versão do Node.js no pipeline. No Cloud Manager, vá para Ambientes > Configuração > Variáveis de ambiente e defina CM_CUSTOM_VAR_NODE_VERSION (ou NODE_VERSION onde aplicável). Execute o pipeline novamente e confirme a versão de Nó nos logs, garantindo que nenhuma versão conflitante esteja definida em pom.xml ou em seu script de compilação.
  4. Para pipelines de pilha completa, defina NODE_VERSION como 20 para usar o Node.js 20 e validar as dependências do projeto para compatibilidade com o Nó 20.
  5. Use o Node.js 22 ou 23 somente onde houver suporte documentado. Se uma build de front-end falhar, reverta para o Nó 18 ou 20 e teste a compatibilidade de dependência.
  6. Valide a compatibilidade de dependência de terceiros testando builds com a nova versão do Node.js e confirmando que não há regressões de front-end. Para problemas específicos do fornecedor, entre em contato diretamente com o fornecedor, já que a Adobe não pode fornecer os detalhes de compatibilidade.
  7. Confirme a correção executando node -v e npm -v nos logs de compilação e acionando uma execução de pipeline completa para verificar se a compilação ui.frontend tem êxito sem erros de incompatibilidade de versão.
  8. Se as compilações ainda falharem, apesar da configuração correta, entre em contato com o Suporte da Adobe com seus logs de pipeline, pom.xml, package.json e a lista de variáveis de ambiente do Cloud Manager.

Para o AEM 6.5 (Managed Services e no local)

  1. Observe que não há uma matriz oficial de suporte ao Node.js para o AEM 6.5. O Node.js é gerenciado pelo cliente, usado apenas para ferramentas de tempo de compilação e dissociado do tempo de execução do AEM.
  2. Ao atualizar Node.js e npm, mantenha package.json e pom.xml consistentes para que as compilações locais e de CI sejam alinhadas (por exemplo, atualização do Nó 12.22.7 para 16.17.0 e do npm 6.14.0 para 8.15.0).
  3. Confirme as versões executando node -v e npm -v localmente e em CI, e verifique se a compilação de front-end foi concluída sem erros de incompatibilidade de versão.
  4. Se a confusão ou os problemas de compilação persistirem, contate o Suporte da Adobe com os detalhes do script de compilação, pom.xml e package.json.

Leitura relacionada

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