Next.js Docker 최적화 전략 : 멀티스테이지 빌드와 standalone 모드

Next.js 프로젝트는 로컬에서는 잘 작동하지만, Docker로 운영 환경에 배포하는 순간 전혀 다른 문제가 발생한다.- 빌드 결과물과 전체 소스를 모두 포함해 이미지 용량이 1GB를 넘고 - 의존성은 바뀌지 않았는데도 매번 설치부터 다시 하게 되고 - 빌드 시간과 배포 속도는 점점 길어지며 - 실행 구조가 복잡해져 운영 환경에서 디버깅이나 관리가 번거로워진다단순히 “실행되는 Docker 이미지”를 만드는 것과 운영 환경에서 최적화된 구조로 빠르고 안정적으로 배포하는 것은 다르다. 이 글에서는 위 문제들을 해결하기 위해내가 직접 사용하고 있는 두 가지 최적화 전략을 공유한다.멀티스테이지 빌드 (Multi-stage Build)Next.js standalone 모드이 두 가지를 함께 적용하면Do..

• format_list_bulleted React
• · 2025. 5. 15.
• textsms

Next.js standalone 배포 "sharp missing in production" 에러 해결하기

Next.js의 next/image 컴포넌트는 이미지 최적화를 위해 서버 측에서 sharp 모듈을 사용합니다. 하지만 Docker 기반의 production 환경에서는 종종 아래와 같은 오류가 발생합니다.Error: 'sharp' is required to be installed in standalone mode for the image optimization to function correctly. 개발 환경에서는 멀쩡히 동작하던 기능이 운영 환경에서 갑자기 실패하는 이유는 무엇일까요? 이 글에서는 해당 오류의 원인과 해결 방법을 명확히 정리해 봅니다.1. 개발 환경에서는 왜 문제가 없을까?개발 중에는 sharp와 관련된 문제가 드러나지 않는 경우가 대부분입니다. 그 이유는 아래와 같습니다.1) 개발 ..

• format_list_bulleted React
• · 2025. 5. 7.
• textsms