Next.js 프로젝트에서 Docker 이미지를 빌드할 때는 Vercel의 권고대로 standalone 옵션을 사용합니다. standalone 은 독립 실행형(standalone)이라는 뜻으로, Next.js프로젝트 에서 웹 애플리케이션 실행에 필요한 최소한의 코드만 추출하여 최적화된 빌드 결과물을 생성한다는 것을 뜻하는데요. 어떻게 Docker 이미지의 용량이 획기적으로 줄어드는지 정리해보았습니다.

1. 불필요한 파일 제거

기본적으로 Docker 이미지를 만들 때는 node_modules를 포함한 전체 프로젝트가 필요하지만, standalone 옵션을 적용하면 실행에 반드시 필요한 파일만 포함하는 최소한의 환경이 구성됩니다. 즉, 개발 환경에서 사용되던 불필요한 파일들(node_modules, pages/, app/ 등)이 대부분 제거되어 이미지 용량이 크게 줄어듭니다.

2. node_modules 최적화

Next.js는 standalone 모드를 활성화하면 실행에 필요한 node_modules만 포함하도록 최적화합니다. 기본적으로 node_modules는 모든 종속성을 포함하기 때문에 매우 무겁지만,
standalone 모드에서는 Next.js 실행에 필요한 패키지만 남기고, 불필요한 개발용 패키지(devDependencies, ESLint, TypeScript 등)는 제외됩니다.

사실상 꼭 실행에 꼭 필요한 node_modules만 남기고 나머지를 제거하는게 포인트입니다.

그리고 당연한 이야기겠지만, Docker 이미지 크기를 줄이면 배포 시간도 단축할 수 있습니다. 일반적으로 도커 이미지는 AWS ECR, Docker Hub 등 원격 레지스트리에 이미지를 푸시하는데요. 용량이 줄어든 만큼 전송 속도가 크게 향상됩니다.

Next.js의 standalone 모드는 불필요한 파일을 제거하고, 실행에 필요한 최소한의 환경만 남겨 Docker 이미지를 최적화하는 유용한 기능입니다. 이를 활용하면 배포 속도 개선, 인프라 비용 절감, 더 빠른 컨테이너 시작 시간 등의 효과를 얻을 수 있습니다.

https://nextjs.org/docs/pages/api-reference/config/next-config-js/output