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 접두사가 있는 환경 변수 (클라이언트 노출)
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 번들에 값이 포함되므로, 브라우저의 개발자 도구를 통해 누구나 이 값을 볼 수 있습니다. 따라서 절대 민감한 정보(비밀 키, 암호 등)를 담아서는 안 됩니다.
핵심 차이점 요약
|
구분 |
|
|
|---|---|---|
|
접근 범위 |
서버 측 전용 (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을 붙여야 합니다.