빌드 명령 및 출력 디렉터리 구성

Getting Orbit to build your project correctly comes down to a handful of fields in Settings: install command, build command, output directory, root directory and Node.js version. Left blank they are…

Orbit를 사용하여 프로젝트를 올바르게 빌드하려면 설정의 몇 가지 필드가 필요합니다: 설치 명령, 빌드 명령, 출력 디렉터리, 루트 디렉터리 및 Node.js 버전입니다. 빈 상태로 두면 자동으로 감지되며, 대부분의 첫 배포 문제는 프레임워크가 실제로 작성하는 내용과 일치하지 않는 자동 감지 값에서 비롯됩니다.

설정을 찾을 수 있는 곳

Orbit에서 프로젝트를 열고 설정 탭으로 이동한 후 빌드 설정 카드를 찾습니다.

필드	역할	빈 상태일 때의 자리 표시자
설치 명령	빌드 전에 종속성이 설치되는 방식	`npm ci (auto-detected)`
빌드 명령	출력을 생성하는 명령	`npm run build (auto-detected)`
출력 디렉터리	빌드 후 Orbit이 게시하는 폴더	`dist (auto-detected)`
루트 디렉터리	모노레포의 경우, 앱이 포함된 하위 디렉터리	`/ (monorepo subdirectory)`
Node.js 버전	빌드 및 실행에 사용할 주 Node 버전	플랫폼 기본값

모든 필드를 비워두어 Orbit이 자동으로 감지하도록 합니다. 빌드 설정 카드에서 저장을 클릭하여 적용합니다.

Orbit 프로젝트 설정의 빌드 설정 카드

빌드 설정을 변경해도 현재 라이브 상태인 배포는 변경되지 않습니다. 새 설정은 다음 배포부터 적용됩니다. 저장 후 재배포하지 않으면 변경 사항이 나타나지 않습니다.

프레임워크 기본값

Next.js

Next.js는 Orbit에서 두 가지 모드를 가지며, 잘못된 모드를 선택하는 것이 가장 흔한 첫 배포 실수입니다.

정적 내보내기 (output: 'export' in next.config.js):

빌드 명령: npm run build
출력 디렉터리: out
서버 모드: 꺼짐

서버 모드 (SSR 또는 ISR), 대부분의 Next.js 앱:

설정의 런타임 아래에서 서버 모드를 켭니다
빌드 명령: npm run build
출력 디렉터리: .next

서버 모드가 활성화되지 않으면 서버 렌더링 Next.js 앱이 정적 파일로 게시됩니다. 홈 페이지는 보통 로드되지만 모든 동적 라우트는 404가 됩니다. 이런 증상이 나타나면 이것이 원인입니다: 서버 모드를 켜고 다른 것을 변경하기 전에 재배포하세요.

Astro

Astro의 출력 폴더는 모든 모드에서 dist입니다. 변경되는 것은 서버 모드가 필요한지 여부입니다.

output: 'static', 기본값: 출력 디렉터리 dist, 서버 모드 꺼짐
output: 'server' 또는 output: 'hybrid': 출력 디렉터리 dist, 서버 모드 켜짐
빌드 명령: npm run build, 또는 astro build

Vite (React, Vue, Svelte)

빌드 명령: npm run build, 또는 vite build
출력 디렉터리: dist

Vite는 vite.config.ts에서 build.outDir을 재정의하지 않는 한 항상 dist로 씁니다. 재정의했다면 출력 디렉터리를 일치하도록 설정하세요.

SvelteKit

빌드 명령: npm run build
출력 디렉터리: build

서버 모드가 필요한지 여부는 어댑터에 따라 다릅니다: 정적 어댑터는 필요 없고, Node 어댑터는 필요합니다.

Nuxt 3

빌드 명령: npm run build
출력 디렉터리: .output
서버 모드: 켜짐

Remix

빌드 명령: npm run build
출력 디렉터리: build
서버 모드: 켜짐

Express 또는 일반 Node API

빌드 명령: npm run build
출력 디렉터리: dist
서버 모드: 켜짐

서버 모드는 빌드 후 npm start을 실행하므로, start 스크립트가 존재하고 서버를 시작하는지 확인하세요.

Create React App

Create React App은 업스트림에서 더 이상 지원되지 않으며 새 프로젝트에는 좋은 선택이 아니지만, 기존 프로젝트는 잘 빌드됩니다.

빌드 명령: npm run build
출력 디렉터리: build

일반 HTML 또는 정적 사이트 생성기

package.json가 없으면 설치 명령을 비워두세요
빌드 명령을 비워두어 저장소를 있는 그대로 게시하거나, 생성기의 명령을 설정하세요
출력 디렉터리: 저장소 루트의 경우 ., 또는 생성기가 쓰는 어떤 폴더든지

Node.js 버전

주 버전 번호만 입력하세요: 18, 20 또는 22. 필드 힌트에서 명시적으로 그렇게 말합니다. 20.11.0 또는 v20 같은 다른 것은 이 필드가 예상하는 것이 아닙니다.

버전은 빌드에 적용되며, 서버 모드가 켜져 있을 때는 런타임에도 적용됩니다.

기본값에 의존하지 말고 버전을 고정하세요. 새로운 Node가 필요한 종속성은 설치 중에 오류가 발생하는데, 이는 "잘못된 Node 버전"이라고 명확히 말하지 않는 경우가 많으며, 버전을 고정하면 이 종류의 오류를 완전히 제거할 수 있습니다.

모노레포

루트 디렉터리를 앱의 경로(예: apps/web)로 설정하세요. Orbit은 설치 및 빌드 명령을 실행하기 전에 해당 디렉터리로 변경하고, 출력 디렉터리는 이에 대한 상대 경로입니다.

필드 힌트는 두 번째, 더 유용한 동작을 명시합니다: 그 경로 외부의 파일만 자동으로 건너뜁니다. 4개의 Orbit 프로젝트가 있는 모노레포는 커밋이 실제로 터치한 앱만 다시 빌드하므로 시간과 빌드 분을 절약할 수 있습니다.

각 환경은 설정의 스테이징: 빌드 재정의 아래에서 루트 디렉터리를 독립적으로 재정의할 수 있으며, 이는 스테이징이 다른 작업 영역을 빌드할 때 유용합니다.

스테이징 재정의

프로젝트에 스테이징 환경이 있으면, 설정에 같은 필드가 있는 스테이징: 빌드 재정의 섹션이 표시됩니다. 거기서 빈 필드는 프로젝트 수준 값을 상속하므로, 예를 들어 스테이징의 빌드 명령만 npm run build:staging으로 변경하고 다른 것은 그대로 둘 수 있습니다.

스테이징은 근처에 자체 관련 설정이 있습니다: 브랜치, 액세스 암호, IP 허용 목록, 실패 시 자동 롤백, 프로덕션 환경 변수 상속 토글입니다.

빌드 캐시

Orbit은 Liftoff 및 Apex 플랜에서 빌드 간 node_modules을 캐시합니다. 배포 세부 정보 페이지에서 캐시 히트 또는 콜드 빌드를 표시하고, 설치 단계 지속 시간을 함께 표시하므로 캐시가 프로젝트에서 어떤 가치를 제공하는지 볼 수 있습니다.

전체 재설치를 강제하려면 설정을 열고 빌드 캐시 지우기를 클릭한 후 확인하세요.

빌드 캐시를 지우는 것은 취소할 수 없으며, 모든 환경의 다음 배포는 처음부터 전체 설치를 실행합니다. 큰 모노레포에서는 빌드가 느릴 수 있으므로 반사적으로 하기보다는 신중하게 실행하세요.

흔한 함정

"빌드는 성공했지만 사이트에 404가 표시됩니다." 출력 디렉터리가 잘못되었습니다: Orbit이 빌드 출력이 아닌 폴더를 게시했습니다. 빌드가 실제로 생성하는 폴더를 확인하세요. Vite는 dist로 쓰고, Next.js 정적 내보내기는 out로 쓰고, Next.js 서버 모드는 .next을 사용하고, Create React App과 Remix는 build로 쓰고, Nuxt는 .output로 씁니다.

"동적 라우트에서만 404, 홈 페이지는 괜찮습니다." 서버 모드가 필요한 앱에서 꺼져 있습니다. 위의 Next.js 섹션을 참조하세요.

첫 배포에서 "Module not found" 설치 단계가 실행되지 않았거나, 로컬에서 사용하는 것과 다른 패키지 관리자로 실행되었습니다. 설치 명령을 명시적으로 설정하세요: npm ci, yarn install --frozen-lockfile, 또는 pnpm install --frozen-lockfile. 또한 정확히 하나의 lockfile을 커밋했는지 확인하세요: package-lock.json과 yarn.lock이 모두 저장소에 있으면, 감지된 패키지 관리자가 예상하는 것이 아닐 수 있습니다.

"Lockfile이 만료되었습니다." npm ci와 frozen-lockfile 동등 항목은 lockfile이 package.json와 다를 때 실행을 거부합니다. 로컬에서 패키지 관리자 설치를 실행하고 다시 생성된 lockfile을 커밋하세요. 이것이 가장 흔한 첫 배포 실패이며 로컬에서는 절대 재현되지 않으므로, 이것이 정확히 혼동을 주는 이유입니다.

"모노레포의 한 앱만 배포되고 있습니다." 그것이 루트 디렉터리가 역할을 하는 것입니다. 각 앱은 자체 루트 디렉터리가 있는 자체 Orbit 프로젝트가 필요합니다.

"잘못된 Node.js 버전입니다." Node.js 버전 필드를 주 버전 번호만으로 설정하세요.

빌드가 메모리 부족이거나 디스크를 채웁니다. 둘 다 빌드 머신의 플랜 제한입니다: Launch는 1 vCPU, 1 GB RAM, 4 GB 디스크를 가집니다. Liftoff는 2, 2 GB, 8 GB를 가집니다. Apex는 4, 4 GB, 16 GB를 가집니다. NODE_OPTIONS=--max-old-space-size=2048을 환경 변수로 추가하면 머신의 실제 RAM까지만 도움이 됩니다. Orbit 플랜 제한을 참조하세요.