DocumentaciónKCS de Experience Cloud

Compatibilidad y compatibilidad con las versiones de Node.js y npm para las versiones de AEM front-end

Última actualización: 7 de julio de 2026

Los módulos front-end de AEM (como ui.frontend con React o Webpack) requieren una versión de Node.js compatible con el entorno de compilación de AEM, y el uso de una versión no compatible o no coincidente provoca errores o incertidumbre en la compilación de la canalización de Cloud Manager al actualizar. Para solucionar el problema, identifique el modelo de implementación, confirme que se admiten las versiones de Node.js y npm de Target, y establezca la versión correcta en la configuración de la canalización.

Descripción description

Entorno

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

Problema/Síntomas

  • Las compilaciones de canalización de Cloud Manager fallan al usar una versión de Node.js no compatible (por ejemplo, al usar el nodo 20 antes de agregar la compatibilidad).
  • La incertidumbre sobre qué versión de npm está empaquetada con una versión de Node.js compatible (por ejemplo, npm 10.8.2 con Node 18 o npm 9.6.7 con Node 23.11.1).

Causa raíz

Los distintos modelos de implementación de AEM administran Node.js de forma diferente. En AEM as a Cloud Service, Node.js forma parte del contenedor de compilación de Cloud Manager con versiones validadas. En AEM 6.5 Managed Services o en línea, Node.js es puramente una dependencia de tiempo de compilación que usted administra y no existe ninguna matriz de soporte oficial. Si se intenta utilizar versiones que aún no se han publicado en Cloud Manager o versiones npm que no coinciden, pueden producirse incompatibilidades de compilación.

Pasos a seguir

  1. Identifique el modelo de implementación: AEM as a Cloud Service, AEM 6.5 Managed Services o AEM 6.5 local.
  2. Para AEM as a Cloud Service, ejecute node -v y npm -v en un paso de generación de canalización y revise las versiones impresas en los registros de generación.
  3. Compare su versión de Node.js de destino con la lista de versiones oficialmente admitidas.

Resolución resolution

Para solucionar el problema, identifique el modelo de implementación de AEM y siga los pasos para su entorno:

Para AEM as a Cloud Service

  1. Compruebe que su versión de Node.js de destino sea compatible. Según la documentación oficial, las versiones principales admitidas son 12, 14, 16, 18, 20, 22 y 23. Compare esta lista con la admitida por Experience League.
  2. Confirme la versión de npm incluida en la versión de Node.js. Ejecute node -v y npm -v en un paso de generación de canalización de Cloud Manager y revise los registros (por ejemplo, los paquetes npm 10.8.2 del nodo 18 y los paquetes npm 9.6.7 del nodo 23.11.1). Si npm informa de un 404 para su versión, que refleja diferencias en el registro público, confirme la versión agrupada real.
  3. Configure la versión de Node.js en la canalización. En Cloud Manager, vaya a Entornos > Configuración > Variables de entorno y establezca CM_CUSTOM_VAR_NODE_VERSION (o NODE_VERSION donde corresponda). Vuelva a ejecutar la canalización y confirme la versión del nodo en los registros, asegurándose de que no se haya definido ninguna versión en conflicto en pom.xml o en el script de compilación.
  4. Para canalizaciones de pila completa, establezca NODE_VERSION en 20 para utilizar Node.js 20 y valide las dependencias del proyecto para la compatibilidad con Node 20.
  5. Utilice Node.js 22 o 23 solo cuando exista soporte documentado. Si falla una compilación del front-end, vuelva al nodo 18 o 20 y pruebe la compatibilidad de dependencias.
  6. Valide la compatibilidad de dependencias de terceros probando las compilaciones con la nueva versión de Node.js y confirmando que no hay regresiones del front-end. Para problemas específicos del proveedor, póngase en contacto directamente con el proveedor de terceros, ya que Adobe no puede proporcionar sus detalles de compatibilidad.
  7. Confirme la corrección ejecutando node -v y npm -v en los registros de compilación y activando una ejecución de canalización completa para comprobar que la compilación de ui.frontend se realice correctamente sin errores de no coincidencia de versiones.
  8. Si las compilaciones siguen fallando a pesar de la configuración correcta, póngase en contacto con el soporte técnico de Adobe con los registros de canalización, pom.xml, package.json y la lista de variables de entorno de Cloud Manager.

Para AEM 6.5 (Managed Services y local)

  1. Tenga en cuenta que no hay una matriz de compatibilidad oficial de Node.js para AEM 6.5. Node.js se administra por el cliente, solo se usa para las herramientas en tiempo de compilación y se desvincula del tiempo de ejecución de AEM.
  2. Al actualizar Node.js y npm, mantenga la coherencia de package.json y pom.xml para que las compilaciones locales y de CI se alineen (por ejemplo, actualizando Node 12.22.7 a 16.17.0 y npm 6.14.0 a 8.15.0).
  3. Confirme las versiones ejecutando node -v y npm -v localmente y en CI, y verifique que la compilación del front-end se complete sin errores de no coincidencia de versiones.
  4. Si persisten los problemas de confusión o compilación, póngase en contacto con el soporte técnico de Adobe y proporcione los detalles del script de compilación, pom.xml y package.json.

Lectura relacionada

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