설명서

AEM as a Cloud Service의 프론트엔드 파이프라인 장애 문제 해결

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

전체 스택 파이프라인을 AEM as a Cloud Service에서 프론트엔드(FE) 전용 파이프라인으로 변환할 때 플랫폼별 종속성 및 엄격한 린팅 요구 사항으로 인해 빌드 오류가 발생할 수 있습니다. Windows 또는 macOS에서 package-lock.json을(를) 생성하면 Linux 기반 Cloud Manager과 호환되지 않을 수 있습니다. 또한 FE 파이프라인은 전체 스택 Maven 빌드에 없는 코드 스타일 검사를 적용합니다.

참고

  • Cloud Manager에서 프론트엔드 파이프라인을 실행하면 npm 설치가 먼저 실행되지 않고, Git에 있는 package-lock.json을(를) 가져와 npm audit --production --audit-level=critical을(를) 실행합니다. 그러나 전체 스택 파이프라인은 프론트엔드-Maven-plugin을 통해 요청하는 Node/NPM 버전을 설치하고 npm 설치를 실행하므로 전체 스택 파이프라인에서는 문제가 표시되지 않습니다.

설명 description

환경

  • 제품: AEM as a Cloud Service - 사이트
  • 파이프라인: Cloud Manager을 통한 FE(프론트엔드 전용) 파이프라인
  • 노드 버전: 14.19.1
  • npm 버전: 6.14.x
  • 로컬 빌드의 운영 체제: Windows(로컬), Linux(Cloud Manager 컨테이너)
  • 필요한 권한: Cloud Manager의 배포 관리자 역할

문제/증상

  • npm 설치 중에 파이프라인이 실패하고 * chokida에서 fsevents에 액세스할 수 없음 r*과(와) 같은 오류가 발생합니다.
  • 누락되었거나 일치하지 않는 package-lock.json개 파일과 관련된 오류
  • 로컬 빌드는 Windows 또는 Mac에서는 성공하지만 Cloud Manager 파이프라인에서는 실패합니다
  • 수백 개의 ESLint/code-style 오류로 인해 FE 전용 파이프라인 오류가 발생하지만 전체 스택 파이프라인은 기본적으로 이러한 검사를 적용하지 않습니다

해결 방법 resolution

다음 단계를 수행하여 문제를 해결하십시오.

  1. package-lock.json이(가) ui.frontend 모듈에 있고 저장소에 커밋되었는지 확인하십시오.

  2. Linux 환경을 사용하여 package-lock.json 및 node_modules을(를) 다시 생성합니다(Linux 또는 Docker용 Windows 하위 시스템 사용). FE 전용 파이프라인에 대한 플랫폼별 종속성 문제를 재현하고 해결하려면 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"

     
    또는 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. Jest, Storybook 및 Webpack과 같은 오래된 종속성을 업데이트합니다.

  4. 남은 종속성 문제를 식별하려면 프로덕션 및 중요 감사 수준 플래그와 함께 npm audit을(를) 사용하십시오. 예: npm audit --production --audit-level=critical

  5. Linux 환경에서 다시 생성된 package-lock.json 파일을 리포지토리에 커밋합니다.

  6. FE 전용 파이프라인에서 사용하는 분기에 변경 사항을 푸시합니다.

  7. Cloud Manager에서 FE 전용 파이프라인을 다시 실행합니다.

  8. 빌드 프로세스 중에 보고된 ESLint/코드 스타일 오류를 해결합니다. 성공적인 배포를 위해서는 모든 lint 오류를 해결해야 합니다.

  9. 유효성 검사 용도로만 필요한 경우 package.json의 빌드 스크립트에서 연결을 일시적으로 제거하십시오. 그러나 프로덕션 용도에는 권장되지 않습니다.

  10. 빌드 단계가 종속성 또는 링크 오류 없이 성공적으로 완료되는지 확인합니다.

  11. 배포가 성공하지만 사이트의 스타일 및 스크립트가 로드되지 않는 경우 Dispatcher 설정 및 CDN 구성을 확인하십시오. 활성화된 vhost에 정적 도메인에 대한 올바른 ServerAlias이(가) 포함되어 있는지 확인하십시오. 단계는 프론트엔드 파이프라인 배포가 웹 사이트를 중단함을 참조하세요.

  12. 파이프라인이 BUILD_NPM_AUDIT_ERROR과(와) 함께 실패하면 충돌하는 SiteConfig 또는 HtmlPageItemsConfig 노드를 제거하십시오. 단계는 AEM as a Cloud Service 프론트엔드 파이프라인에서 BUILD_NPM_AUDIT_ERROR를 해결하는 방법을 참조하십시오.

참고

  • FE 전용 파이프라인은 전체 스택 Maven 빌드보다 엄격한 코드 스타일 검사를 시행합니다. 배포 전에 모든 lint 오류를 해결해야 합니다.

  • package.json에 다음 스크립트를 추가하여 JavaScript 및 CSS 린팅 오류를 수정하는 프로세스를 자동화할 수 있습니다.

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

이렇게 하면 npm run lint:fix을(를) 실행하여 변경 내용을 푸시하기 전에 많은 린팅 문제를 자동으로 수정할 수 있습니다.

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