Next.js 환경 변수 NEXT_PUBLIC 접두사 역할

NEXT_PUBLIC 접두사를 붙이면 변수의 접근 범위가 완전히 달라집니다. 이 차이점을 이해하는 것이 안전하고 효율적인 Next.js 애플리케이션을 구축하는 데 중요합니다.

`NEXT_PUBLIC` 접두사가 없는 환경 변수 (서버 전용)

NEXT_PUBLIC 접두사 없이 선언된 환경 변수는 서버 측(Server-Side)에서만 접근이 가능합니다.

접근 범위: 서버 측 렌더링(getServerSideProps), 정적 사이트 생성(getStaticProps), API 라우트 (app/api 또는 pages/api 폴더 내부) 등 Node.js가 실행되는 환경에서만 process.env.변수명으로 접근할 수 있습니다.
처리 방식: 이 변수들은 클라이언트로 전송되는 JavaScript 번들에 포함되지 않습니다. 오직 서버가 코드를 실행하는 시점에만 메모리에 로드되어 사용됩니다.
주요 용도: 데이터베이스 접속 정보, 외부 API의 비밀 키, 내부 서비스의 인증 토큰 등 민감하거나 클라이언트에 노출되어서는 안 되는 값을 저장하는 데 사용됩니다.
- DATABASE_URL
- API_SECRET_KEY
- CMS_API_TOKEN
보안: 클라이언트에 절대 노출되지 않으므로, 애플리케이션의 핵심 비밀 정보를 안전하게 관리할 수 있습니다.

NEXT_PUBLIC 접두사를 붙여 선언한 환경 변수는 서버와 클라이언트(브라우저) 양쪽에서 모두 접근이 가능합니다.

접근 범위: 서버 측 코드는 물론, 브라우저에서 실행되는 클라이언트 측 JavaScript 코드(React 컴포넌트 등)에서도 process.env.NEXT_PUBLIC_변수명으로 접근할 수 있습니다.
처리 방식: Next.js는 빌드 시점에 NEXT_PUBLIC으로 시작하는 모든 환경 변수의 값을 JavaScript 코드에 그대로 삽입(inlining)합니다. 즉, 최종적으로 생성된 JS 파일 안에 변수 값이 텍스트로 포함됩니다.
주요 용도: 클라이언트 측 코드에서 알아야 하는 공개적인 정보를 저장하는 데 사용됩니다.
- NEXT_PUBLIC_API_BASE_URL (프론트엔드에서 호출할 백엔드 API의 기본 주소)
- NEXT_PUBLIC_FIREBASE_API_KEY (Firebase 웹 클라이언트 설정용 공개 키)
- NEXT_PUBLIC_GOOGLE_ANALYTICS_ID (구글 애널리틱스 추적 ID)
보안 (매우 중요): JavaScript 번들에 값이 포함되므로, 브라우저의 개발자 도구를 통해 누구나 이 값을 볼 수 있습니다. 따라서 절대 민감한 정보(비밀 키, 암호 등)를 담아서는 안 됩니다.

구분	`NEXT_PUBLIC` 미사용 (예: `DB_HOST`)	`NEXT_PUBLIC_` 사용 (예: `NEXT_PUBLIC_API_URL`)
접근 범위	서버 측 전용 (Node.js 환경)	서버 및 클라이언트(브라우저)
처리 방식	서버 런타임에만 사용	빌드 시점에 JS 번들에 값이 인라인됨
주요 용도	비밀 키, DB 접속 정보, 내부 인증 토큰	공개 API 주소, 기능 플래그, 외부 서비스의 공개 키
보안	높음 (클라이언트에 노출되지 않음)	주의 필요 (누구나 볼 수 있는 공개 정보만 저장)

"사용자와 상호작용을 하는가?"

아니오 (No): 브라우저가 알 필요 없는 데이터를 가져오거나 처리한다면, NEXT_PUBLIC 접두사를 붙이지 마세요.
- 예를 들면 비밀번호
예 (Yes): 사용자의 상호작용에 따라 클라이언트 컴포넌트에서 직접 API를 호출해야 한다면, NEXT_PUBLIC 접두사를 붙여야 합니다.
- 예를들면 사용자가 버튼을 클릭했을 때 사용자 정보를 가져오는 경우 ${process.env.NEXT_PUBLIC_API_URL}/users

# 서버에서만 접근 가능
DATABASE_PASSWORD=12345678

# 클라이언트에서도 접근 가능
NEXT_PUBLIC_API_URL=https://api.test.com

"그럼 전부 다 NEXT_PUBLIC 안 붙이면 되는 거 아닌가?"

클라이언트에서 사용해야 하는 값이라면 반드시 NEXT_PUBLIC을 붙여야 합니다.