설명서Experience Cloud KCS

AEM 프론트엔드 빌드에 대한 Node.js 및 npm 버전 지원 및 호환성

마지막 업데이트: 2026년 7월 7일

AEM 프론트엔드 모듈(예: React 또는 Webpack이 있는 ui.frontend)에는 AEM 빌드 환경과 호환되는 Node.js 버전이 있어야 하며, 지원되지 않거나 일치하지 않는 버전을 사용하면 Cloud Manager 파이프라인 빌드가 실패하거나 업그레이드 시 불확실성이 발생합니다. 이 문제를 해결하려면 배포 모델을 식별하고, target Node.js 및 npm 버전이 지원되는지 확인하고 파이프라인 구성에서 올바른 버전을 설정합니다.

설명 description

환경

  • Adobe Experience Manager as a Cloud Service
  • AEM Managed Services (AEM 6.5)
  • Adobe Experience Manager 6.5 (온-프레미스)

문제/증상

  • 지원되지 않는 Node.js 버전을 사용하는 경우(예: 지원이 추가되기 전에 Node 20 사용) Cloud Manager 파이프라인 빌드가 실패합니다.
  • 지원되는 Node.js 버전과 번들로 제공되는 npm 버전에 대한 불확실성(예: Node 18이 있는 npm 10.8.2 또는 Node 23.11.1이 있는 npm 9.6.7).

근본 원인

다른 AEM 배포 모델은 Node.js를 다르게 처리합니다. AEM as a Cloud Service에서 Node.js는 검증된 버전이 있는 Cloud Manager 빌드 컨테이너의 일부입니다. AEM 6.5 Managed Services 또는 온프레미스에서 Node.js는 단순히 관리하는 빌드 시간 종속항이며, 공식 지원 매트릭스가 없습니다. Cloud Manager에서 아직 릴리스되지 않은 버전 또는 일치하지 않는 npm 버전을 사용하려고 하면 빌드가 호환되지 않을 수 있습니다.

재현 단계

  1. 배포 모델(AEM as a Cloud Service, AEM 6.5 Managed Services 또는 AEM 6.5 On-Premise)을 식별합니다.
  2. AEM as a Cloud Service의 경우 파이프라인 빌드 단계에서 node -v 및 npm -v을(를) 실행하고 빌드 로그에서 인쇄된 버전을 검토하십시오.
  3. Target Node.js 버전을 공식적으로 지원되는 버전 목록과 비교합니다.

해결 방법 resolution

문제를 해결하려면 AEM 배포 모델을 식별한 다음 환경에 대한 단계를 수행합니다.

AEM as a Cloud Service용

  1. 대상 Node.js 버전이 지원되는지 확인합니다. 공식 문서에 따라 지원되는 주요 버전은 12, 14, 16, 18, 20, 22 및 23입니다. Experience League 지원 목록에 대해 상호 확인합니다.
  2. Node.js 버전과 번들로 제공된 npm 버전을 확인합니다. Cloud Manager 파이프라인 빌드 단계에서 node -v 및 npm -v을(를) 실행하고 로그를 검토합니다(예: Node 18 번들 npm 10.8.2 및 Node 23.11.1 번들 npm 9.6.7). npm이 공용 레지스트리 차이점을 반영한 404 버전을 보고하는 경우 실제 번들 버전을 확인하십시오.
  3. 파이프라인에서 Node.js 버전을 구성합니다. Cloud Manager에서 환경 > 구성 > 환경 변수(으)로 이동하여 CM_CUSTOM_VAR_NODE_VERSION(또는 해당되는 경우 NODE_VERSION)을(를) 설정합니다. 파이프라인을 다시 실행하고 로그에서 노드 버전을 확인하여 pom.xml 또는 빌드 스크립트에서 충돌하는 버전이 정의되지 않도록 하십시오.
  4. 전체 스택 파이프라인의 경우 Node.js 20을 사용하도록 NODE_VERSION을(를) 20으로 설정하고 Node 20 호환성에 대한 프로젝트 종속성을 확인하십시오.
  5. 문서화된 지원이 있는 경우에만 Node.js 22 또는 23을 사용하십시오. 프론트엔드 빌드에 실패하면 노드 18 또는 20으로 되돌아가서 종속성 호환성을 테스트하십시오.
  6. 새 Node.js 버전으로 빌드를 테스트하고 프론트엔드 회귀가 없는지 확인하여 타사 종속성 호환성을 확인합니다. 공급업체별 문제는 Adobe에서 호환성 세부 정보를 제공할 수 없으므로 서드파티 공급업체에 직접 문의하십시오.
  7. 빌드 로그에서 node -v 및 npm -v을(를) 실행하고 전체 파이프라인 실행을 트리거하여 ui.frontend 빌드가 버전 불일치 오류 없이 성공했는지 확인하여 수정 사항을 확인하십시오.
  8. 올바른 구성에도 불구하고 빌드가 계속 실패하는 경우 파이프라인 로그 pom.xml, package.json 및 Cloud Manager 환경 변수 목록을 사용하여 Adobe 지원 센터에 문의하십시오.

AEM 6.5(Managed Services 및 온-프레미스)용

  1. AEM 6.5에 대한 공식 Node.js 지원 매트릭스는 없습니다. Node.js는 고객 관리형이며 작성 시간 툴링에만 사용되고 AEM 런타임과 분리됩니다.
  2. Node.js 및 npm을 업데이트할 때 로컬 및 CI 빌드가 정렬되도록 package.json 및 pom.xml을(를) 일관되게 유지하십시오(예: Node 12.22.7을 16.17.0으로, npm 6.14.0을 8.15.0으로 업그레이드).
  3. 로컬로 CI에서 node -v 및 npm -v을(를) 실행하여 버전을 확인하고, 버전 불일치 오류 없이 프론트엔드 빌드가 완료되는지 확인하십시오.
  4. 혼동 또는 빌드 문제가 남아 있는 경우 Adobe 지원 센터에 문의하여 빌드 스크립트 세부 정보, pom.xml 및 package.json을(를) 확인하십시오.

관련 읽기

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