Next.js에서 .next 폴더는 어떤 역할을 할까?

• .next 폴더는 무엇인가요?
• .next 폴더는 언제 생성되나요?
• .next 폴더 안에는 무엇이 들어가나요?
• 개발 모드와 빌드 모드에서의 차이
• .next 폴더를 삭제해도 되나요?
• .next 폴더를 Git에 올리지 않는 이유
• 배포할 때 .next 폴더는 어떻게 사용되나요?
• 자주 생기는 오해
• 실무에서 기억할 체크리스트

.next 폴더는 무엇인가요?

.next 폴더는 Next.js 프로젝트를 실행하거나 빌드할 때 프레임워크가 자동으로 만드는 내부 작업 폴더입니다. 프로젝트 루트에서 npm run dev를 실행하거나 npm run build를 실행하면, Next.js는 사용자가 작성한 app, pages, components, styles 같은 소스 파일을 읽고 실행 가능한 형태로 변환합니다. 그 변환 결과가 저장되는 대표적인 위치가 바로 .next입니다.

쉽게 말하면 .next는 개발자가 직접 코드를 작성하는 폴더가 아니라, Next.js가 애플리케이션을 실행하기 위해 만들어 두는 결과물 저장소입니다. 그래서 src나 app처럼 평소에 열어서 컴포넌트를 작성하는 폴더와는 성격이 다릅니다. 내부 파일을 이해하면 빌드와 배포 흐름을 파악하는 데 도움이 되지만, 일반적인 기능 개발 과정에서 이 폴더 안의 파일을 직접 수정할 일은 거의 없습니다.

예를 들어 사용자가 app/page.tsx를 수정하면 Next.js는 변경 사항을 감지하고 브라우저에 반영할 수 있도록 필요한 파일을 다시 처리합니다. 이때 중간 처리 결과, 서버 실행에 필요한 파일, 캐시 정보 등이 .next 아래에 저장될 수 있습니다. 따라서 .next는 소스가 아니라 소스를 바탕으로 만들어지는 실행 및 빌드 결과물이라고 이해하면 가장 정확합니다.

.next 폴더는 언제 생성되나요?

.next 폴더는 보통 두 가지 상황에서 생성됩니다. 첫 번째는 개발 서버를 실행할 때이고, 두 번째는 프로덕션 빌드를 만들 때입니다. 프로젝트를 처음 내려받은 직후에는 .next 폴더가 없을 수 있습니다. 하지만 npm install로 의존성을 설치한 뒤 npm run dev를 실행하면 프로젝트 루트에 .next 폴더가 생기는 것을 볼 수 있습니다.

개발 모드에서는 Next.js가 빠른 피드백을 위해 필요한 파일을 계속 만들고 갱신합니다. 개발자가 코드를 저장하면 변경된 부분을 다시 컴파일하고, 브라우저가 새 결과를 볼 수 있도록 내부 상태를 업데이트합니다. 이 과정에서 .next 폴더는 계속 변할 수 있습니다. 그래서 개발 중에 .next의 용량이나 내부 파일 개수가 달라지는 것은 이상한 일이 아닙니다.

프로덕션 빌드에서는 npm run build를 실행할 때 .next 폴더가 더 명확한 빌드 산출물 저장소로 사용됩니다. 이때 Next.js는 페이지와 라우트, 서버 렌더링에 필요한 코드, 정적 생성 결과, 최적화된 번들 등을 준비합니다. 실제 서비스 환경에서 사용할 수 있는 형태로 애플리케이션을 정리하는 과정이라고 보면 됩니다.

npm run dev
npm run build
npm run start

npm run dev는 개발 중 확인을 위한 실행이고, npm run build는 배포 가능한 결과를 만들기 위한 명령입니다. npm run start는 일반적으로 이미 만들어진 프로덕션 빌드를 실행할 때 사용합니다. 이 흐름을 보면 .next가 단순한 임시 폴더가 아니라, Next.js 실행 방식과 밀접하게 연결된 폴더라는 점을 알 수 있습니다.

.next 폴더 안에는 무엇이 들어가나요?

.next 폴더 안의 구조는 Next.js 버전, 프로젝트 설정, 라우팅 방식, 빌드 옵션에 따라 달라질 수 있습니다. 따라서 특정 하위 폴더 이름을 모두 외우려고 하기보다, 어떤 성격의 파일들이 들어가는지 큰 범주로 이해하는 편이 좋습니다. 대표적으로 빌드 결과물, 페이지와 라우트 관련 파일, 캐시와 최적화 파일이 들어갑니다.

• 사용자가 작성한 코드를 실행 가능한 형태로 변환한 빌드 결과물
• app 또는 pages 라우팅에 필요한 서버 및 클라이언트 파일
• 정적 생성, 서버 렌더링, 이미지 최적화 등에 사용되는 보조 파일
• 다음 실행이나 다음 빌드를 빠르게 하기 위한 캐시 데이터

예를 들어 app 라우터를 사용하는 프로젝트라면 서버 컴포넌트와 클라이언트 컴포넌트를 처리한 결과가 내부적으로 나뉘어 저장될 수 있습니다. pages 라우터를 사용하는 프로젝트라면 페이지 단위의 빌드 결과가 다른 형태로 나타날 수 있습니다. 하지만 실무에서 중요한 판단은 비슷합니다. .next 안의 파일은 사람이 직접 유지보수하는 원본이 아니라, Next.js가 필요에 따라 생성하고 갱신하는 파일입니다.

캐시 파일도 중요합니다. 개발 서버가 이전 작업 결과를 재사용하면 매번 모든 파일을 처음부터 처리하지 않아도 됩니다. 덕분에 개발 서버 시작 속도나 코드 변경 반영 속도가 개선될 수 있습니다. 반대로 이 캐시가 꼬였다고 의심되는 경우에는 .next를 삭제하고 다시 실행하는 방식으로 문제를 확인할 수 있습니다.

개발 모드와 빌드 모드에서의 차이

개발 모드의 .next와 빌드 모드의 .next는 같은 폴더를 사용하지만 목적이 조금 다릅니다. npm run dev에서는 빠른 개발 경험이 우선입니다. 파일 변경을 감지하고, 필요한 부분만 다시 처리하고, 브라우저에 즉시 반영하는 흐름이 중요합니다. 그래서 개발 중의 .next는 계속 갱신되는 작업 공간에 가깝습니다.

반면 npm run build에서는 실제 배포에 사용할 결과를 만드는 것이 목적입니다. 이 단계에서는 라우트별 렌더링 방식, 정적 페이지 생성 여부, 서버에서 실행될 코드, 클라이언트에 전달될 번들 등이 정리됩니다. 빌드가 실패하면 .next의 결과물도 신뢰할 수 없으므로, 오류 메시지를 먼저 확인하고 필요한 경우 폴더를 지운 뒤 다시 빌드해 보는 것이 좋습니다.

초급자가 자주 헷갈리는 부분은 개발 서버에서 잘 보인다고 해서 프로덕션 빌드가 항상 성공한다는 보장은 없다는 점입니다. 개발 모드에서는 느슨하게 넘어가던 문제가 빌드 단계에서 타입 오류, 라우트 처리 오류, 서버 전용 코드와 클라이언트 전용 코드의 혼용 문제로 드러날 수 있습니다. 이때 .next는 원인이 아니라 결과가 쌓이는 장소에 가깝습니다. 문제를 고칠 때는 보통 .next 내부 파일이 아니라 원본 소스 파일을 수정해야 합니다.

.next 폴더를 삭제해도 되나요?

대부분의 경우 로컬 개발 환경에서 .next 폴더는 삭제해도 됩니다. .next는 원본 소스가 아니라 재생성 가능한 결과물이기 때문입니다. 개발 서버가 이상하게 동작하거나, 이전 빌드 결과가 남아 있는 것 같거나, 캐시 문제로 의심되는 상황에서는 .next를 삭제한 뒤 다시 실행하는 방식이 흔히 사용됩니다.

rm -rf .next
npm run dev

위 명령은 로컬 프로젝트에서 .next 폴더를 지우고 개발 서버를 다시 시작하는 예시입니다. 삭제 후 npm run dev를 실행하면 Next.js가 필요한 파일을 다시 만듭니다. npm run build를 실행해도 마찬가지로 빌드 결과가 새로 생성됩니다.

다만 삭제해도 된다는 말이 언제나 아무 영향도 없다는 뜻은 아닙니다. 삭제 직후 첫 실행이나 첫 빌드는 캐시를 다시 만들어야 하므로 시간이 더 걸릴 수 있습니다. .next 용량이 지나치게 커졌거나 오래된 결과물이 의심될 때도 로컬에서는 삭제 후 재생성으로 확인할 수 있습니다. 그래도 용량 문제가 반복된다면 빌드 산출물뿐 아니라 의존성, 패키지 캐시, 이미지나 정적 파일 크기까지 함께 점검해야 합니다. 또 배포 서버에서 실행 중인 프로덕션 애플리케이션의 .next를 임의로 지우는 것은 별개의 문제입니다. 로컬 개발 환경에서는 재생성하면 되지만, 운영 환경에서는 배포 방식과 실행 구조를 확인한 뒤 처리해야 합니다.

.next 폴더를 Git에 올리지 않는 이유

.next 폴더는 일반적으로 Git에 커밋하지 않습니다. 이유는 단순합니다. 이 폴더는 소스 코드가 아니라 빌드 결과물이기 때문입니다. 같은 소스 코드와 같은 설정, 같은 의존성 환경이 있으면 다시 만들 수 있는 파일을 저장소에 넣을 필요가 없습니다. 오히려 커밋하면 저장소 용량이 커지고, 변경 이력이 불필요하게 복잡해질 수 있습니다.

또한 .next 안의 파일은 환경마다 달라질 수 있습니다. 운영체제, Node.js 버전, 패키지 버전, 환경 변수, 빌드 옵션에 따라 결과가 달라질 여지가 있습니다. 한 개발자의 로컬에서 만들어진 .next를 다른 사람의 환경에 그대로 공유하는 것은 안정적인 협업 방식이 아닙니다.

.next
node_modules
.env.local

그래서 많은 Next.js 프로젝트의 .gitignore에는 .next가 포함됩니다. 저장소에는 app, pages, components, next.config.js, package.json처럼 원본과 설정에 해당하는 파일을 남기고, .next처럼 다시 만들 수 있는 결과물은 제외하는 것이 일반적인 관리 방식입니다.

배포할 때 .next 폴더는 어떻게 사용되나요?

배포 과정에서 .next는 빌드 결과물로 사용됩니다. 다만 사용자가 직접 .next 폴더를 압축해서 올리는 방식인지, 배포 플랫폼이 서버에서 직접 빌드하는 방식인지는 환경에 따라 다릅니다. 예를 들어 Vercel 같은 플랫폼은 저장소의 소스 코드를 받아서 배포 과정 중 npm run build를 실행하고, 그 결과로 생성된 .next를 기반으로 서비스를 구성합니다.

직접 서버를 운영하는 경우에는 흐름을 더 명확히 이해해야 합니다. 일반적으로 서버에서 의존성을 설치하고 npm run build를 실행한 뒤, npm run start로 프로덕션 서버를 실행합니다. 이때 npm run start는 이미 준비된 빌드 결과를 사용하므로, 정상적인 .next 결과물이 필요합니다. 설정에 따라 standalone 형태의 산출물을 만들어 필요한 실행 파일만 배포하는 방식도 사용할 수 있으므로, 실제 서버에 무엇을 복사하고 어떤 명령으로 실행할지는 프로젝트의 Next.js 설정과 배포 스크립트를 기준으로 확인해야 합니다.

하지만 이것이 .next를 저장소에 커밋해야 한다는 뜻은 아닙니다. 배포 환경에서 빌드하도록 구성되어 있다면 저장소에는 원본 코드만 있으면 됩니다. 반대로 특수한 배포 구조에서 빌드된 산출물을 별도로 패키징해야 한다면, 그 방식에 맞춰 결과물을 포함할 수 있습니다. CI/CD에서는 보통 소스 체크아웃, 의존성 설치, 빌드, 배포 순서로 처리하고, 빌드 시간을 줄이기 위해 캐시를 활용할 수는 있지만 캐시와 최종 산출물을 혼동하지 않는 것이 중요합니다. 핵심은 .next가 배포에 쓰일 수는 있지만, 원칙적으로는 빌드 단계에서 생성되는 산출물이라는 점입니다.

자주 생기는 오해

첫 번째 오해는 .next 폴더를 수정하면 앱의 기능을 고칠 수 있다고 생각하는 것입니다. 실제로는 그렇지 않습니다. .next 내부 파일을 수정해도 다음 개발 서버 실행이나 다음 빌드에서 덮어써질 가능성이 높습니다. 기능 수정은 app/page.tsx, components/Header.tsx, next.config.js 같은 원본 파일에서 해야 합니다.

두 번째 오해는 .next가 생겼다는 것 자체가 오류라고 생각하는 것입니다. .next는 정상적인 Next.js 프로젝트라면 자연스럽게 생기는 폴더입니다. 프로젝트 루트에 갑자기 나타났다고 해서 삭제해야 하는 문제 파일은 아닙니다. 개발과 빌드에 필요한 작업 공간으로 보면 됩니다.

세 번째 오해는 .next를 지우면 프로젝트가 망가진다고 걱정하는 것입니다. 로컬 개발 환경에서는 대체로 괜찮습니다. 원본 코드와 설정, 의존성이 남아 있다면 Next.js가 다시 생성합니다. 다만 삭제 후에도 같은 오류가 반복된다면 문제는 .next 자체가 아니라 소스 코드, 설정, 패키지 버전, 환경 변수 쪽에 있을 가능성이 큽니다.

• .next는 직접 수정하는 소스 폴더가 아닙니다.
• .next가 생기는 것은 정상 동작입니다.
• 로컬에서는 삭제 후 재생성할 수 있습니다.
• 반복되는 빌드 오류는 원본 코드와 설정을 기준으로 확인해야 합니다.

실무에서 기억할 체크리스트

.next 폴더를 실무에서 다룰 때는 복잡하게 생각할 필요가 없습니다. 평소에는 신경 쓰지 않아도 되고, 문제가 생겼을 때 역할을 알고 있으면 됩니다. 개발 서버가 이상하게 꼬였거나 변경 사항이 제대로 반영되지 않는 것처럼 보이면 .next를 삭제한 뒤 다시 실행해 볼 수 있습니다. 빌드 오류가 나면 .next 내부를 고치기보다 터미널의 오류 메시지와 원본 파일을 먼저 확인해야 합니다.

협업에서는 .gitignore에 .next가 들어가 있는지 확인하는 것이 좋습니다. 누군가 실수로 .next를 커밋하면 리뷰에서 제외하도록 안내해야 합니다. 이 폴더는 변경이 잦고 용량도 커질 수 있어 코드 리뷰 품질을 떨어뜨릴 수 있습니다.

배포에서는 플랫폼이 어디에서 빌드하는지 확인하면 됩니다. 저장소를 기반으로 배포 플랫폼이 직접 npm run build를 실행한다면 .next를 커밋할 필요가 없습니다. 직접 서버에 올리는 방식이라면 빌드 단계와 실행 단계를 분리해서, 언제 .next가 생성되고 어떤 산출물이 서버에서 필요한지 확인해야 합니다. standalone 배포를 쓴다면 일반적인 npm run start 흐름과 패키징 대상이 달라질 수 있으므로 배포 스크립트도 함께 봐야 합니다.

• 로컬 개발 중 생긴 .next는 정상적인 자동 생성 폴더입니다.
• 캐시가 의심될 때는 rm -rf .next 후 다시 실행해 볼 수 있습니다.
• .next 내부 파일을 직접 수정하지 않습니다.
• .next는 보통 Git에 커밋하지 않습니다.
• 배포 환경에서는 npm run build 결과로 생성된 .next가 실행에 사용될 수 있습니다.
• CI/CD에서는 .next 커밋 여부보다 빌드 위치, 캐시 정책, 산출물 패키징 방식을 확인합니다.

정리하면 .next 폴더는 Next.js가 애플리케이션을 실행하고 배포 가능한 형태로 만들기 위해 사용하는 빌드 결과물과 캐시 공간입니다. 직접 관리해야 하는 원본 소스가 아니라 필요할 때 다시 만들어지는 결과물이라는 점만 기억해도 대부분의 판단이 쉬워집니다. 개발자는 .next를 고치는 대신 원본 코드와 설정을 관리하고, 문제가 의심될 때 재생성하는 방식으로 접근하면 됩니다.