
Next.js 애플리케이션을 Docker 이미지로 만드는 과정은 비교적 간단하다. 의존성을 설치하고, next build를 실행한 다음 서버를 시작하면 된다.
그런데 배포에 필요한 파일이 어디까지인지 설명하려고 하면 조금 어지럽다.
빌드할 때 설치한 node_modules를 전부 가져가야 할까. 소스 코드와 .next 디렉터리는 어디까지 필요할까. 빌드가 끝난 뒤 필요 없는 파일을 삭제하면 이미지 크기도 줄어들까.
output: 'standalone'은 이 문제를 다룰 때 자주 등장하는 설정이다. 다만 이 설정이 줄여 주는 범위와 Docker에서 결정해야 하는 범위는 각각 이해할 필요가 있다.
이 글에서는 Next.js 공식 문서와 v16.4.6의 파일 추적·복사 구현을 기준으로, 빌드 결과가 실행 이미지에 들어가기까지의 흐름을 정리했다. 용량 감소율이나 속도 개선 수치는 실제 애플리케이션에서 측정할 항목으로 남겼다.
이미지가 커지는 이유부터 나눠서 생각하기
Docker 이미지에는 애플리케이션 코드 외에도 여러 파일이 들어간다.
Node.js를 실행하기 위한 운영체제와 런타임, 설치한 의존성, 빌드 도구, 빌드 결과물, 정적 파일이 모두 용량을 차지한다. Dockerfile 구성에 따라 소스 코드와 패키지 매니저 캐시까지 남을 수 있다.
예를 들어 같은 단계에서 의존성을 설치하고 빌드한 뒤 서버를 실행한다면,
빌드를 위해 준비한 파일들이 실행 이미지에도 남게 된다. 이 상태에서 이미지가 크다는 이유만으로 node_modules부터 줄이려고 하면 실제로 비중이 큰 부분을 놓칠 수 있다.
우선 고려할 것은 최종 이미지의 구성이다.
docker image history --no-trunc로 어느 단계에서 큰 변경이 생겼는지 확인하고, 컨테이너 내부의 디렉터리 크기를 함께 비교하면 원인을 좁힐 수 있다. 베이스 이미지의 비중이 큰지, 의존성 설치 단계가 큰지, 소스를 복사하면서 불필요한 파일까지 들어갔는지에 따라 수정할 부분도 달라진다.
이때 빌드 컨텍스트 크기와 최종 이미지 크기도 구분해야 한다.
.dockerignore는 빌더에 전달할 파일의 범위를 줄이는 데 사용한다. 컨텍스트에 포함된 파일이 이미지에 저장되는지는 이후 COPY 등의 작업에 달려 있다. 컨텍스트가 작아졌다는 사실만으로 실행 이미지도 같은 만큼 줄었다고 판단하기는 어렵다. Docker 빌드 컨텍스트 문서
Standalone은 어떤 파일을 남길까
Next.js는 빌드 과정에서 실행에 필요한 파일을 추적한다. Output File Tracing을 통해 생성된 .nft.json에는 관련 파일 경로가 기록된다.
여기에 output: 'standalone'을 설정하면 추적 결과를 바탕으로 .next/standalone 디렉터리에 배포용 파일을 복사하고, 실행용 server.js를 생성한다. 필요한 node_modules 파일도 이 디렉터리에 포함된다. Next.js output 문서
따라서 Standalone을 이해할 때는 일반 빌드에서도 만들어지는 추적 결과와, 그 결과를 이용해 파일을 모으는 과정을 구분하면 편하다.
의존성 전체를 배포 환경에서 다시 설치하는 방식과 비교하면, 배포 대상으로 삼는 파일의 범위가 달라진다. package.json에 선언된 패키지 목록에서 더 내려가, 서버 실행에 필요하다고 추적된 파일을 가져오는 것이다.
그렇다고 .next/standalone 디렉터리 하나만 복사하면 모든 구성이 끝나는 것은 아니다.
public과 .next/static은 기본 복사 대상에 포함되지 않는다. 정적 파일을 CDN에서 제공할지, 같은 서버에서 제공하도록 함께 배치할지 결정해야 한다. 같은 서버에서 제공한다면 실행 디렉터리 구조에 맞춰 복사해야 한다. Next.js output 문서
이 부분은 실행 확인에도 영향을 준다. 서버가 시작되고 HTML이 응답하더라도 JavaScript나 CSS 파일 경로가 잘못되면 화면은 정상적으로 동작하지 않을 수 있다.
Standalone 적용 후에는 서버 시작 여부와 함께 정적 리소스 요청, 실제 사용하는 서버 경로까지 검증 범위에 포함해야 한다.
필요한 파일이라는 판단은 어디서 나올까
Output File Tracing을 이해하려면 파일이 포함되는 근거를 따라가는 편이 좋다.
@vercel/nft는 진입 파일에서 시작해 모듈 의존성과 파일 접근을 분석한다. 모듈 해석 과정에서는 패키지의 진입점과 exports 같은 정보가 영향을 주고, 파일 경로를 계산하는 표현식도 분석 대상이 된다. 일부 동적인 표현식에서는 특정 디렉터리의 파일들을 후보로 포함할 수 있다. vercel/nft 문서
여기서 추적 결과를 실제 실행 기록처럼 이해하면 설명이 어긋난다.
특정 요청을 한 번 실행했을 때 사용한 파일 목록과, 코드 분석을 통해 실행 중 필요할 수 있다고 판단한 파일 목록은 범위가 다를 수 있다. 설정이나 요청에 따라 실행 경로가 달라지는 코드도 고려하기 때문이다.
그래서 예상보다 많은 파일이 포함될 수 있고, 반대로 분석하기 어려운 경로에서는 필요한 파일이 누락될 수도 있다.
예를 들어 서버에서 JSON이나 템플릿 파일을 읽는 코드가 있다고 하자. 경로가 고정되어 있는 경우와 요청값을 조합해 경로를 만드는 경우에는 추적 결과가 달라질 여지가 있다. 실제 결과는 사용 중인 버전과 표현식에 따라 확인해야 한다.
추적 결과가 예상과 다르다면 다음 순서로 범위를 좁힐 수 있다.
- 해당 서버 경로의
.nft.json에서 파일 포함 여부를 확인한다. - 경로가 어떤 값으로 계산되는지 확인한다.
- 추적된 파일이 Standalone 디렉터리에도 복사됐는지 비교한다.
- 원래 소스 디렉터리에 접근할 수 없는 환경에서 해당 요청을 실행한다.
Next.js v16.4.6의 collectBuildTraces에는 nodeFileTrace를 호출하면서 추적 루트와 작업 디렉터리를 전달하는 코드가 있다. copyTracedFiles에서는 추적 결과를 읽어 파일을 복사하고 링크를 처리한다. 설정을 이해할 때도 이 두 과정을 연결하면 결과 디렉터리의 구조를 설명하기 쉬워진다. 추적 수집 구현, 파일 복사 구현
빌드에 필요했던 파일은 어디까지 가져갈까
Standalone을 적용해도 Dockerfile에서 빌드 디렉터리 전체를 복사하면 불필요한 파일이 실행 이미지에 들어갈 수 있다.
여기서 Multi-stage Build가 연결된다.
빌드 단계에는 의존성 설치와 컴파일에 필요한 환경을 준비한다. 실행 단계는 별도의 베이스에서 시작하고, 앞 단계에서 만들어진 산출물 중 필요한 파일을 복사한다.
Multi-stage는 이런 단계 분리를 제공한다. 어떤 파일이 애플리케이션 실행에 필요한지는 Dockerfile을 작성하는 쪽에서 결정해야 한다. Standalone 산출물을 복사 대상으로 삼으면 Next.js의 파일 추적 결과를 그 결정에 활용할 수 있다. Docker Multi-stage Build 문서
두 기능의 효과를 비교하려면 적용 순서도 고려해야 한다.
먼저 일반 빌드 산출물과 production 의존성을 별도 실행 이미지에 배치할 수 있다. 그다음 같은 실행 베이스를 유지하면서 Standalone 산출물로 교체하면, 파일 추적을 적용하면서 추가로 달라진 부분을 비교하기 좋다.
반대로 Multi-stage 적용과 Standalone 설정, 베이스 이미지 교체를 한 번에 진행하면 이미지가 줄어도 어느 변경의 영향이 컸는지 설명하기 어려워진다.
특히 베이스 이미지는 크기 외에 네이티브 의존성의 실행 환경도 고려해야 한다. 빌드 단계에서 준비한 파일을 다른 운영체제 구성의 실행 단계로 옮길 때는 호환성 검증이 필요하다.
파일을 지웠는데도 이미지에 남는 이유
실행 이미지에서 필요 없는 파일을 지우는 방법도 생각할 수 있다. 다만 Docker 이미지에서는 삭제한 시점이 영향을 준다.
이미지 레이어는 생성된 뒤 변경되지 않는다. 이후 레이어가 파일의 추가·수정·삭제를 기록하면서 컨테이너에서 보이는 파일시스템을 구성한다. 앞선 레이어에 저장된 파일을 다음 레이어에서 삭제하더라도 이전 레이어의 데이터는 남는다. Docker 이미지 레이어 문서
예를 들어 큰 임시 파일을 생성한 RUN과 삭제한 RUN을 분리하면, 최종 컨테이너에서는 파일이 보이지 않아도 이미지에는 해당 데이터를 담은 레이어가 포함될 수 있다.
같은 RUN 안에서 임시 파일을 생성하고 삭제하는 경우에는 그 단계가 끝났을 때 남는 파일시스템 변경이 달라진다. Multi-stage에서 임시 파일을 빌드 단계에 두고 결과만 복사하는 방식도 고려할 수 있다.
따라서 레이어 개수만으로 이미지 크기를 판단하기는 어렵다. 각 레이어에 어떤 파일이 들어가는지, 이후 단계에서 같은 파일을 다시 쓰는지, 임시 데이터를 어느 단계까지 남기는지가 더 구체적인 확인 대상이다.
모노레포에서는 추적 범위를 어디까지 넓혀야 할까
모노레포에서는 Next.js 앱 바깥에 공유 패키지나 런타임 파일이 있을 수 있다.
기본 프로젝트 디렉터리 밖의 파일을 추적해야 한다면 outputFileTracingRoot를 고려하게 된다. 이 설정은 파일 추적의 루트 범위를 지정한다. 필요한 외부 파일을 포함하는 과정에서는 outputFileTracingIncludes도 함께 검토할 수 있다. Next.js 추적 설정과 모노레포 안내
루트를 저장소 전체로 넓혔다고 모든 파일이 자동으로 복사되는 것은 아니다. 실제 추적 관계와 포함 규칙에 따라 결과가 만들어진다.
여기에 Docker 빌드 컨텍스트도 별도로 고려해야 한다. Next.js 설정에서 추적 범위를 넓혔더라도, 빌드 컨테이너 안에 공유 파일이 들어오지 않았다면 해당 파일을 읽을 수 없다.
경로를 따라가면 확인할 지점이 세 개 생긴다.
- Docker 빌드 환경에 파일이 전달됐는가.
- Next.js 추적 결과에 파일이 포함됐는가.
- 최종 실행 이미지의 예상 경로에 파일이 배치됐는가.
모노레포에서는 앱의 상대 경로가 산출물 구조에 반영될 수 있으므로 생성된 server.js의 위치와 실행 디렉터리도 함께 확인해야 한다. 단일 앱에서 사용한 복사 경로를 그대로 적용하기 전에 실제 산출물 구조를 기준으로 Dockerfile을 맞추는 편이 낫다. Next.js 파일 복사 구현
이미지 크기가 줄면 배포도 빨라질까
전송해야 하는 데이터가 줄어드는 것은 배포 시간을 줄일 수 있는 조건이다. 다만 이미지 크기만으로 전체 시간을 예측하기는 어렵다.
빌드에는 의존성 설치와 Next.js 빌드, 이미지 생성과 내보내기 과정이 있다. 배포에는 레지스트리 전송, 대상 서버의 이미지 다운로드와 압축 해제, 컨테이너 시작과 준비 상태 확인이 포함된다.
어느 구간이 오래 걸리는지에 따라 이미지 최적화의 효과도 달라질 수 있다.
반복 빌드에서는 캐시 조건도 영향을 준다. 의존성 파일과 소스 코드를 복사하는 순서에 따라 소스 변경이 의존성 재설치까지 이어질 수 있다. 캐시 마운트나 외부 캐시를 사용하는 경우에는 같은 Dockerfile이라도 빌드 환경에 따라 소요 시간이 달라진다. Docker 캐시 최적화 문서
실제 효과를 확인하려면 다음 항목을 나눠 기록할 필요가 있다.
| 측정 항목 | 함께 기록할 조건 |
|---|---|
| 최종 이미지 크기 | 베이스 이미지, 대상 아키텍처 |
| 의존성 설치 시간 | 패키지 캐시 유무, lockfile 변경 여부 |
| Next.js 빌드 시간 | 버전, 빌드 명령, 빌드 캐시 유무 |
| 이미지 push 시간 | 레지스트리에 이미 존재하는 레이어 |
| 이미지 pull 시간 | 배포 대상의 로컬 레이어 보유 여부 |
| 서비스 준비 시간 | 시작 시 수행하는 작업, 준비 상태 판단 기준 |
docker image ls에 표시되는 크기와 이번 배포에서 실제로 전송한 데이터도 구분해야 한다. 레이어를 재사용하는 조건에서는 전체 이미지 크기 중 일부만 새로 전송될 수 있다. 여러 이미지가 레이어를 공유한다면 이미지별 크기의 합과 호스트의 실제 디스크 사용량도 달라질 수 있다. Docker 이미지 크기 문서
현재 문서와 구현으로 확인할 수 있는 것은 파일을 추리고, 복사하고, 이미지에 저장하는 방식까지다.
실제 애플리케이션에서는 동일한 소스와 실행 베이스를 유지한 채 일반 빌드와 Standalone 산출물을 비교하고, 정적 파일과 서버 기능이 모두 동작하는지 검증할 예정이다. 그다음 캐시 조건을 나눠 빌드·전송·서비스 준비 시간을 측정하면, 줄어든 파일이 어느 구간에 영향을 줬는지 기록할 수 있다.
틀린 내용이나 궁금한 점은 댓글로 남겨주세요.