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_URLAPI_SECRET_KEYCMS_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을 붙여야 합니다.