output: standalone / 빌드 산출물 구조¶
Next.js는 next.config.js의 output 설정에 따라
빌드 산출물의 구성과 배포 방식이 근본적으로 달라진다.
이는 단순한 최적화 옵션이 아니라,
“무엇을 실행 대상으로 삼는가”에 대한 계약 정의에 가깝다.
1. 기본(default) output¶
- 빌드 결과는
.next/디렉터리에 생성됨 - 실행 시 다음 요소가 함께 필요:
.next/node_modules/package.json
- 런타임에서:
- 외부 의존성
- 환경 변수
변경이 비교적 유연함
운영 특성¶
- 전통적인 Node.js 배포 방식과 유사
- 파일 누락 시 즉시 실행 실패 가능
- 디스크 사용량 증가
2. output: "standalone"¶
- 실행에 필요한 파일만 선별한 독립 산출물 생성
.next/standalone/디렉터리 기준으로 실행- 주요 특징:
- 필요한
node_modules만 내부에 포함 - 실행 엔트리(
server.js)가 고정됨
- 필요한
운영 특성¶
- 배포 대상 파일 범위가 명확
- 컨테이너/Docker 환경에 적합
- 실행 경로·파일 구조 변경에 취약
standalone은 “가벼운 빌드”가 아니라
배포 구조를 고정하는 선택이다.
3. 운영 리스크 및 주의사항¶
- 다음 항목은 별도로 복사/관리해야 함
public/디렉터리- 환경 변수 파일
- 외부 설정 파일
- OS / native module 의존성은 여전히 존재
- 런타임 환경 변경 시:
- 재빌드 필요 가능성 높음
4. 운영 기준 (Baseline)¶
output설정은 프로젝트 표준으로 고정한다output: "standalone"사용 시:- 실행 경로
- 복사 대상 파일 목록
을 반드시 문서화한다
- default ↔ standalone 전환은:
- 단순 설정 변경이 아닌
- 배포 모델 변경으로 간주한다
5. 운영 체크리스트¶
- 현재
output설정 확인 - 실행 엔트리(
server.js) 경로 점검 -
public/및 설정 파일 포함 여부 확인 - 배포 스크립트와 산출물 구조 일치 여부 점검