Orbit
Kapsule Migrator 빌드 실패 문제 해결
When an Orbit build fails, the deployment detail page gives you the full log plus a categorised failure summary and a suggested fix. This guide walks through reading that page, the failures Orbit…
Orbit 빌드가 실패하면 배포 상세 페이지에서 전체 로그, 분류된 실패 요약 및 제안된 해결책을 제공합니다. 이 가이드는 해당 페이지를 읽는 방법, Orbit이 이름으로 인식하는 실패, 인식하지 못하는 실패, 빌드는 성공했지만 사이트가 여전히 잘못된 경우에 대해 설명합니다.
실패 읽기
- Orbit에서 프로젝트를 엽니다.
- 배포 탭을 엽니다.
- 상태가 실패인 배포를 클릭합니다.
- 로그를 읽기 전에 위의 실패 요약을 먼저 읽은 다음 로그 자체를 읽습니다.
Orbit은 모든 실패에 카테고리를 할당합니다: 메모리 부족, 컴파일 오류, 테스트 실패, Lint 오류, 설치 오류, 네트워크 오류, 시간 초과 또는 알 수 없는 오류. 카테고리는 단 한 줄의 로그를 읽기 전에 어느 파이프라인 부분을 살펴봐야 하는지 알려줍니다.
또한 AI 진단 받기 버튼이 있습니다. 로그의 마지막 120줄과 감지된 프레임워크 및 실패 카테고리를 읽고 일반 언어로 설명을 반환합니다.
진단은 AI가 생성함, 작동 전에 확인으로 표시됩니다. 코드베이스의 권위자가 아닌 올바른 로그 줄을 가리키는 매우 좋은 포인터로 취급하세요. 무언가를 변경하기 전에 참조하는 줄을 읽으세요.
빌드가 시작되지 않고 대기 중에 갇혀 있으면 아래의 대기 중인 빌드 섹션으로 건너뜁니다.
Orbit이 이름으로 인식하는 실패
이들은 배포 페이지에서 특정 제안된 해결책이 함께 제공됩니다.
| Orbit이 감지하는 것 | 의미 | 해결책 |
|---|---|---|
| 누락된 모듈 | import가 설치되지 않은 패키지를 가리킵니다 | package.json에 패키지를 추가하고 커밋하거나 import 경로의 오타를 수정하세요 |
ERESOLVE 충돌 | npm이 피어 의존성을 충족할 수 없습니다 | package.json에서 충돌을 해결하거나 설정의 설치 명령에 --legacy-peer-deps를 추가하세요 |
| TypeScript 오류 | 빌드 중 타입 검사 실패 | 나열된 오류를 수정하세요. 타사 타입 문제의 경우 tsconfig.json에서 skipLibCheck: true를 수행하세요 |
| 메모리 부족 | 빌드가 빌드 머신의 RAM을 초과했습니다 | NODE_OPTIONS=--max-old-space-size=2048을 환경 변수로 추가하거나 더 큰 빌드 머신을 가진 플랜으로 이동하세요 |
| 빌드 디스크 가득 참 | 빌드가 디스크를 채웠습니다 | 예상보다 큰 node_modules 또는 아티팩트를 찾거나 더 큰 빌드 디스크를 가진 플랜으로 이동하세요 |
| 빌드 시간 초과 | 빌드가 30분 중단에 도달했습니다 | 빌드 캐시를 활성화하고, 번들 크기를 줄이거나, 무엇이 정지되어 있는지 찾으세요 |
| 패키지를 찾을 수 없음(404) | 의존성이 해당 이름 또는 버전에 존재하지 않습니다 | package.json에서 오타를 확인하거나 패키지가 게시되었는지 확인하세요 |
| ESLint 오류 | Lint 오류가 빌드를 차단했습니다 | 수정하거나 프레임워크 구성에서 lint가 빌드를 실패하지 않도록 중지하세요 |
| 구문 오류 | 파싱할 수 없는 소스 | 누락된 괄호, 닫히지 않은 문자열 또는 Node 버전이 지원하지 않는 구문 |
| 파일을 찾을 수 없음 | 참조된 파일이 저장소에 없습니다 | 커밋되었는지 확인하고 경로의 대소문자를 확인하세요 |
| 잠금 파일이 오래됨 | 잠금 파일이 package.json와 일치하지 않습니다 | 로컬로 패키지 관리자의 설치를 실행하고 업데이트된 잠금 파일을 커밋하세요 |
잠금 파일 불일치는 단일 최고 첫 배포 실패이며, 로컬에서는 절대 발생하지 않기 때문에 가장 혼란스럽습니다. npm ci, yarn install --frozen-lockfile 및 pnpm install --frozen-lockfile은 모두 잠금 파일이 package.json과 불일치할 때 진행을 거부합니다. 로컬로 잠금 파일을 재생성하고 커밋하세요.
단계별 일반적인 실패
의존성 설치 실패
설치 단계에서 오류가 발생했습니다.
- 잘못된 패키지 관리자. Orbit은 잠금 파일에서 npm, yarn 또는 pnpm을 선택합니다. 둘 이상의 잠금 파일이 커밋된 경우 선택이 예상한 것이 아닐 수 있습니다. 사용하지 않는 파일을 삭제하거나 설정에서 설치 명령을 명시적으로 설정하세요.
- 비공개 레지스트리. 의존성이 비공개 레지스트리에서 오는 경우 인증 토큰은 빌드 시간에 환경 변수로 사용 가능해야 하며
.npmrc는 이를 참조해야 합니다. - Node.js 버전 불일치. 일부 패키지는 최소 Node 버전을 필요로 합니다. 설정에서 Node.js 버전을 주 버전 번호로 설정하세요:
18,20또는22. - 대형 모노레포에서 메모리 부족.
npm install대신npm ci을 사용하고 더 큰 빌드 머신을 가진 플랜을 고려하세요.
빌드 명령 실패
빌드 단계에서 오류가 발생했습니다.
- TypeScript 또는 lint 오류. Orbit은 작성된 그대로 빌드 명령을 실행합니다. 빌드가 로컬에서 실패하면 여기서도 실패합니다.
- 누락된 빌드 시간 환경 변수. 빌드 중에 읽는 변수는 런타임이 아닌 빌드 실행 전에 존재해야 합니다. 환경 변수 탭에 추가하고 재배포하세요. 배포 후에 추가된 빌드 시간 변수는 소급적으로 적용되지 않습니다.
- 모노레포에서 잘못된 루트 디렉토리. 설정에서 루트 디렉토리를 앱의 경로로 설정하세요. 예를 들어
apps/web.
빌드 시간 초과
빌드는 모든 플랜에서 실시간 30분에 중단됩니다. 지속적으로 접근하는 경우:
- 입력을 기다리는 프로세스의 로그를 확인하세요. 프롬프트하는 빌드는 정지된 빌드입니다.
- 필요한 경우가 아니면 대규모 의존성 트리에서
--legacy-peer-deps를 피하세요. - 빌드 캐시가 사용 중인지 확인하세요. Liftoff 및 Apex 플랜에 포함되어 있으며 배포 페이지는 캐시 히트 또는 콜드 빌드를 표시합니다.
- 더 많은 빌드 vCPU를 가진 플랜으로 이동하세요. Kapsule Orbit 플랜 제한을 참조하세요.
빌드가 시작되지 않음
대기 중 상태로 갇혀 있는 배포는 빌드 슬롯을 기다리고 있습니다. 상세 페이지는 큐 위치와 사용 중인 동시 빌드 슬롯 수를 표시하고 하나가 해제되면 자동으로 빌드를 시작합니다. Launch 및 Liftoff는 1개의 동시 빌드를 허용합니다. Apex는 3개를 허용합니다.
계정 전체에서 진행 중인 모든 것을 Kapsule Orbit에서 확인할 수 있으며 큐를 선택합니다.
배포가 다른 것도 실행되지 않은 상태로 대기 중인 경우 대기되기보다는 보류될 가능성이 높습니다. 다음을 확인하세요:
- 승인 대기 중, 프로덕션 승인 필요 설정이 켜진 경우
- 프로젝트의 배포 잠금
- 현재 시간이나 요일을 차단하는 배포 동결 일정
- 파이프라인에서 대기 중인 CI 필수 검사
- 같은 커밋의 스테이징 배포를 기다리는 프로덕션 전 스테이징 성공 필요
빌드가 완전히 건너뜀
푸시가 배포를 전혀 생성하지 않은 경우 의도적으로 필터링되었을 가능성이 높습니다:
- 무시된 경로: 푸시의 모든 파일이
*.md또는docs/**같은 패턴과 일치합니다 - 분기 무시 패턴: 분기가
dependabot/*같은 것과 일치합니다 - 루트 디렉토리: 푸시가 이 프로젝트의 모노레포 하위 디렉토리를 건드리지 않았습니다
- 분기 미리보기 꺼짐, 그리고 푸시가 프로덕션이나 스테이징으로 가지 않았습니다
빌드는 성공했지만 사이트가 잘못됨
녹색 빌드와 깨진 사이트는 거의 항상 코드 문제보다는 구성 문제입니다.
모든 페이지에서 404. 출력 디렉토리가 잘못되었습니다: Orbit이 빌드 출력이 아닌 폴더를 게시했습니다. 빌드가 실제로 무엇을 쓰는지 확인하세요. 일반적인 값은 dist, .next, out, build 및 .output입니다.
동적 경로에서만 404. 앱이 실행 중인 서버를 필요로 하지만 정적 파일로 제공됩니다. 설정의 런타임 아래에서 서버 모드를 켜세요. 이는 SSR이 있는 Next.js, Remix, Nuxt 및 정적 내보내기가 아닌 다른 모든 것에 필요합니다.
배포 후 자산 404, 이미 사이트에 있던 사용자의 경우. 이들은 이전 페이지를 로드했으며 더 이상 존재하지 않는 이전 번들 URL을 요청하고 있습니다. 설정에서 스큐 보호를 켜세요. 이는 새 배포가 라이브 상태가 된 후 보존 기간 동안 이전 빌드의 아티팩트를 사용 가능하게 유지합니다.
환경 변수가 런타임에 정의되지 않았습니다. 변수의 범위가 실제로 이 환경을 포함하는지, 배포가 변경 이후인지 확인하세요. 배포 상세 페이지는 정확히 어떤 키가 빌드 시간에 주입되었으며 현재 구성과 비교하여 차이를 표시합니다.
프레임워크별 빌드 설정은 빌드 명령 및 출력 디렉토리 구성에 있습니다.
재시도
실패한 배포 페이지에서:
- 빌드 재시도는 같은 커밋을 다시 실행합니다.
- 더 많은 재시도 옵션, 그 다음 캐시 초기화로 재시도, 빌드 캐시를 먼저 삭제합니다.
Orbit이 자동으로 재시도하도록 할 수 있습니다. 설정의 빌드 자동 재시도는 네트워크 실패 또는 시간 초과 같은 인프라 오류로 인한 실패한 빌드를 최대 3회까지 다시 대기열에 넣습니다. 의도적으로 코드 오류는 재시도하지 않으므로 컴파일, lint 또는 테스트 실패는 절대 반복되지 않습니다.
캐시를 초기화하여 재시도하면 환경의 캐시된 node_modules을 삭제하며 실행 취소할 수 없습니다. 그 후의 다음 빌드는 느릴 것입니다. 그것이 요점이지만 대형 모노레포에서 조건 반사처럼 하지 마세요.
잘못된 빌드가 사용자에게 도달하는 것을 중지
배포가 이미 라이브 상태가 되었고 무언가를 깨트린 경우 압력 하에서 앞으로 수정하려고 하지 말고 롤백하세요. 롤백은 이미 빌드된 아티팩트를 승격하고 몇 초 정도 걸립니다. 배포 롤백을 참조하세요.
조사하는 동안 추가 배포를 중지하려면 프로젝트에서 배포 잠금을 클릭하세요. 푸시 트리거 배포는 잠금 해제할 때까지 건너뛰어지며 수동 배포는 여전히 작동하므로 수정 사항을 배포할 수 있습니다.
Orbit이 이것을 자동으로 하도록 할 수도 있습니다: 실패 시 자동 롤백은 프로덕션 배포가 실패할 때 마지막 건강한 배포를 복원하며, 상태 확인 경로는 새 배포가 15초 이내에 2xx로 응답하지 않을 때 복원합니다.
계속 문제가 있음
로그가 오류 메시지 없이 단순히 끝나면 빌드 프로세스가 가장 가능성이 높습니다. 메모리 부족이거나 빌드 머신이 회수되었습니다. 한 번 재시도하세요. 같은 방식으로 두 번 실패하면 KPanel에서 티켓을 열거나 support@kapsulehost.com에 이메일을 보내고 상세 페이지에 표시된 배포 ID를 포함하세요.