Vite와 Next.js에서 ENV/MODE/NODE_ENV 정리

 

React(Vite)에서 Next.js로 마이그레이션하며 env 관리와 런타임 모드가 헷갈렸던 경험이 있어서 정리하고자 글을 작성하게 되었습니다.

 

1. Vite의 핵심 개념: mode

Vite는 mode라는 별도의 개념이 있습니다.

mode는 어떤 .env 파일을 로드할지를 결정하는 환경 프로파일 이름입니다.

 

✔️ 기본 동작

명령어	기본 mode 값	로드되는 파일
vite dev	development	.env.development
vite build	production	.env.production

 

✔️ mode는 자유롭게 지정 가능

vite build --mode staging // -> .env.staging 로드
vite dev --mode abc // -> .env.abc 로드

즉 mode는 개발자가 원하는 이름으로 무한하게 만들 수 있습니다.

 

2. 하지만 중요한 사실

Vite의 mode는 dev 서버의 런타임 환경을 바꾸지 않습니다.

 

예를 들어

pnpm dev --mode production

이렇게 해도 dev 서버는 여전히 development 모드로 동작합니다.

 

정리:

항목	값
dev 서버의 동작 모드	development
NODE_ENV	development
import.meta.env.MODE	production
로드되는 env 파일	.env.production

 

즉, mode는 env 파일을 선택하는 역할만 하고 런타임을 바꾸지 않습니다.

 

3. Next.js는 mode 개념이 없다

Next.js는 다음과 같이 동작합니다.

명령어	NODE_ENV 값
next dev	development
next build	production
next start	production (빌드 결과 실행)

→ Next.js는 Vite의 mode 같은 커스텀 환경 이름을 지원하지 않습니다.

→ 대신 .env.local, .env.production, .env.development만 사용합니다.

 

즉 Next.js는 오직 NODE_ENV = dev / prod / test 흐름으로만 환경을 구분합니다.

 

4. NODE_ENV는 무엇인가?

NODE_ENV는 Node.js 런타임의 표준 환경 변수입니다.

가능한 값은 보통 3개:

• development
• production
• test

✔️ NODE_ENV는 앱의 실제 런타임 동작을 바꾼다

 

예를 들어:

NODE_ENV = development일 때

• HMR (HOT Reload) 동작
• 디버그 로그 다 나옴
• 미니파이/트리쉐이킹 X
• 느슨한 검증 및 Dev 전용 경고 출력
• 서버 응답 속도보다 개발 편의성 우선

NODE_ENV = production 일 때

• 코드가 완전히 최적합/압축됨
• React의 dev 경고 삭제
• 성능 중심으로 동작
• 콘솔 로그 최소화
• API/DB 라이브러리가 실제 운영 모드로 동작

즉, NODE_ENV는 실제 런타임의 행동 방식 자체를 바꿉니다.

 

5. 요약

✔️ Vite

• mode는 "어떤 env 파일을 로드할지" 결정
• dev 서버는 무조건 development 모드로 동작
• build는 무조건 production 최적화 적용
• mode가 runtime을 바꾸지는 않음

✔️ Next.js

• mode 자체가 없음
• NODE_ENV로만 환경이 구분됨
• dev/prod 환경의 실제 동작이 명확히 다름

✔️ NODE_ENV

• Node.js 런타임 환경
• dev와 prod는 내부 동작이 완전히 다름
• Next.js는 이 값으로 모든 환경을 판단

 

6. Vite -> Next 마이그레이션 시 주의점

기능	Vite	Next.js
커스텀 모드	가능 (--mode staging)	불가능
env 파일 구분	.env.staging 가능	.env.production / .env.development만
env 접근	import.meta.env	process.env.NEXT_PUBLIC_*
런타임 모드 제어	mode X NODE_ENV O	NODE_ENV만

 

---

출처

https://vite.dev/guide/env-and-mode

Vite

https://nextjs.org/docs/pages/guides/environment-variables

Guides: Environment Variables | Next.js