빌드 설정, 환경 변수, 빌드 실패 해결

빌드 설정은 프로젝트의 설정 화면 빌드 및 배포 항목에서, 환경 변수는 환경 변수 화면에서 바꾸실 수 있습니다. 바꾼 설정과 환경 변수는 다음 배포부터 적용됩니다. 이미 끝난 배포에는 영향이 없으니, 바로 반영하려면 새로 배포하거나 재배포해 주세요.

어떤 빌드 설정을 바꿀 수 있나요

• 프레임워크: 고르면 그 프레임워크의 기본 빌드 명령과 출력 디렉터리가 채워집니다.
• 루트 디렉터리: 앱이 저장소 루트가 아닌 폴더에 있을 때 적습니다.
• 설치 명령: 비워 두면 잠금 파일을 보고 자동으로 고릅니다.
• 빌드 명령: 빌드할 때 실행할 명령입니다.
• 출력 디렉터리: 빌드가 끝난 뒤 정적 파일이 생기는 폴더입니다. 이 폴더의 내용이 배포됩니다.
• Node.js 버전: 18, 20, 22 중에서 고르실 수 있습니다.
• SPA 폴백: 없는 경로를 index.html 로 보냅니다. 클라이언트 라우팅을 쓰는 앱이라면 켜 주세요.

패키지 매니저는 어떻게 정해지나요

설치 명령을 비워 두면 잠금 파일로 판단합니다.

• pnpm-lock.yaml 이 있으면 pnpm install --frozen-lockfile
• yarn.lock 이 있으면 yarn install
• bun.lockb 또는 bun.lock 이 있으면 bun install
• package-lock.json 이 있으면 npm ci
• 잠금 파일 없이 package.json 만 있으면 npm install

잠금 파일은 루트 디렉터리에서 먼저 찾고, 없으면 저장소 루트에서 찾습니다. 다른 방식이 필요하면 설치 명령을 직접 적어 주세요.

모노레포는 어떻게 배포하나요

저장소를 가져올 때 프로젝트 설정 화면의 루트 디렉터리에 앱이 있는 폴더(예: apps/web)를 적고 다시 감지를 누르면 그 폴더의 package.json 으로 프레임워크를 다시 감지합니다. 같은 저장소에서 루트 디렉터리를 달리해 여러 프로젝트로 가져오실 수도 있습니다.

환경 변수는 어떻게 넣나요

환경 변수 화면에서 변수 추가를 누르거나, .env 붙여넣기로 .env 파일 내용을 한꺼번에 넣으실 수 있습니다.

• 적용 대상: 프로덕션, 프리뷰 중 하나 이상을 고릅니다. 프리뷰에는 특정 브랜치를 지정할 수 있고, 비워 두면 모든 프리뷰 브랜치에 적용됩니다.
• 비밀 값: 켜고 저장하면 화면에서 값을 다시 볼 수 없습니다. 값을 바꿀 때는 새 값을 입력해 주세요.
• 이름 규칙: 영문자, 숫자, 밑줄(_)만 쓸 수 있고 숫자로 시작할 수 없습니다. PATH, HOME 처럼 빌드 환경이 쓰는 일부 이름과 PX_ 로 시작하는 이름은 쓸 수 없습니다.

환경 변수는 빌드할 때 주입됩니다. 정적 사이트로 배포되므로, 빌드 결과물에 들어간 값은 방문자 브라우저에서도 보일 수 있습니다. 외부에 노출되면 안 되는 키는 프런트엔드 코드에서 쓰지 마세요.

빌드 로그는 어디서 보나요

배포 목록에서 배포를 누르면 배포 상세 화면에 빌드 로그가 나옵니다. 빌드 중에는 실시간으로 갱신되고, 로그 복사로 전체를 복사하실 수 있습니다.

빌드가 실패합니다

로그 맨 아래의 오류부터 확인해 주세요. 자주 있는 원인은 다음과 같습니다.

1. 출력 디렉터리가 없거나 비어 있음: 빌드는 됐지만 설정한 출력 디렉터리에 파일이 없는 경우입니다. 프레임워크가 실제로 파일을 만드는 폴더로 맞춰 주세요. 예를 들어 Angular 17 이상은 출력이 dist/<프로젝트 이름>/browser 입니다.
2. Next.js 서버 기능 사용: next.config 에 output: 'export' 가 없거나, SSR, API 라우트, 미들웨어를 쓰면 정적 내보내기가 되지 않습니다.
3. 산출물 한도 초과: 배포 하나의 산출물은 500MB, 파일 20,000개까지입니다. 큰 동영상이나 원본 파일은 빼 주세요.
4. 빌드 제한 시간 초과: 플랜별로 빌드 제한 시간이 있습니다(Free 10분, Pro 30분, Ultra 이상 45분).
5. 잠금 파일 불일치: npm ci 나 pnpm install --frozen-lockfile 은 package.json 과 잠금 파일이 맞지 않으면 실패합니다. 로컬에서 잠금 파일을 갱신해 커밋해 주세요.
6. 환경 변수 누락: 빌드에 필요한 변수가 해당 대상(프로덕션 또는 프리뷰)에 들어 있는지 확인해 주세요.

설정을 고친 뒤에는 새로 푸시하거나 배포 메뉴의 재배포로 같은 커밋을 다시 빌드하실 수 있습니다.

빌드가 "대기 중 (빌드 슬롯)" 에서 멈춰 있습니다

플랜의 동시 빌드 수가 모두 쓰이고 있다는 뜻입니다. 오류가 아니며, 앞선 빌드가 끝나 자리가 비면 자동으로 시작됩니다. 급하지 않은 빌드는 배포 취소로 멈춰 자리를 비울 수도 있습니다.

푸시했는데 배포가 만들어지지 않습니다

• 커밋 메시지에 [skip deploy], [skip ci], [ci skip] 이 있으면 그 푸시는 배포하지 않습니다.
• 설정의 자동 배포가 꺼져 있으면 푸시해도 배포되지 않습니다. 배포 탭에서 직접 배포해 주세요.
• 프리뷰 배포가 꺼져 있으면 프로덕션 브랜치가 아닌 브랜치는 배포되지 않습니다.
• 포크한 저장소에서 온 풀 리퀘스트는 보안을 위해 배포하지 않습니다.
• 최근 24시간 배포 한도를 다 썼거나 프로젝트 한도를 넘은 경우에도 새 배포가 막힙니다. 플랜별 한도, 액세스 토큰, 프로젝트 관리를 참고해 주세요.

도움이 필요하면

1:1 문의에서 서비스를 Parallax Cloud 로 골라 주시고, 프로젝트 이름, 실패한 배포의 ID 나 주소, 빌드 로그의 오류 부분을 붙여 주세요. 로그에 비밀 값이 찍혀 있다면 그 부분은 지우고 보내 주세요. 액세스 토큰이나 비밀 값은 저희가 요청하지 않습니다.