Next.js 환경변수, 공개해도 되는 값과 서버에 남길 값을 가르는 기준

Tap to zoom

AI에게 "환경변수 읽어줘"라고 시킨 뒤 화면에 undefined가 나오면, 변수 이름만 고치며 시간을 쓰기 쉽다. 먼저 할 일은 그 값을 브라우저가 꼭 알아야 하는지 가르는 것이다. 브라우저에서 써야 하는 공개값이라면 NEXT_PUBLIC_ 접두사, 배포 환경, 새 빌드 순서로 좁힌다. API 키처럼 비밀이어야 하는 값이라면 접두사를 붙여 화면으로 보내는 해결법은 멈춰야 한다.

이 순서를 따르면 AI가 제안한 설정을 그대로 복사하기 전에, 어떤 값이 비어야 정상인지부터 판별할 수 있다. Next.js 공식 문서는 접두사가 없는 환경변수를 서버 전용으로 두며, NEXT_PUBLIC_ 값은 클라이언트 자바스크립트에 빌드 시 포함된다고 설명한다. Next.js 환경변수 공식 가이드를 열어 현재 버전의 동작도 함께 확인해 두는 편이 안전하다.

Tap to zoom

화면에서 쓸 값인지부터 나누면 첫 원인이 보인다

"use client"가 있는 컴포넌트, 클릭 처리, 브라우저에서 실행되는 화면 코드라면 일반 환경변수는 읽히지 않는다. 서버와 브라우저는 같은 process.env를 공유하는 한 공간이 아니기 때문이다. 이때 공개해도 되는 분석 식별자나 공개 API 주소처럼 화면에 필요한 값만 NEXT_PUBLIC_로 시작하게 한다.

반대로 결제 키, 데이터베이스 비밀번호, 서버 전용 토큰은 화면에 필요하다는 이유만으로 접두사를 붙이면 안 된다. 비밀값을 화면에서 읽게 만들려는 순간에는 코드 경로를 서버 API로 바꾼다. 서버 컴포넌트나 Route Handler에서 비밀값을 읽고, 브라우저에는 필요한 결과만 돌려주는 편이 맞다. 서버 작업과 화면 작업이 섞일 때는 AI 수정과 원래 작업을 분리해 확인하는 Git worktree 루틴처럼 변경 범위를 작게 유지하면 되돌리기도 쉽다.

NEXT_PUBLIC_는 공개 표시이자 빌드 시점 약속이다

공개 가능한 값인데도 화면이 비어 있다면 변수 이름을 두 번 확인한다. 예를 들어 .env.local에 NEXT_PUBLIC_API_BASE=https://example.com을 넣었다면 코드에서도 process.env.NEXT_PUBLIC_API_BASE처럼 정적인 이름으로 읽어야 한다. Next.js는 process.env[name]처럼 이름을 변수로 만든 동적 조회를 클라이언트 번들에 넣지 않는다.

여기서 더 중요한 점은 접두사가 보안 우회 기능이 아니라는 사실이다. NEXT_PUBLIC_ 값은 next build 때 브라우저로 전달될 자바스크립트 안에 고정될 수 있다. 따라서 로컬에서 접두사를 추가하고 화면이 보인다고 해도, 그 값이 방문자에게 보여도 되는 값인지 다시 확인해야 한다. 패키지 설치와 설정 수정이 함께 꼬였을 때는 AI 코딩 결과를 merge 가능한 상태로 바꾸는 테스트 증거 루틴의 diff·test 순서처럼 변경 전후를 비교하는 습관이 도움이 된다.

Tap to zoom

Vercel에서는 환경 선택과 새 배포까지 한 묶음이다

Vercel에서만 값이 비어 있으면, 변수 이름을 바꾸기 전에 값을 어느 환경에 저장했는지 본다. Development, Preview, Production은 서로 다른 배포 상황이다. Preview에만 넣은 값을 Production 사이트에서 기대하거나, Production 값을 바꾼 뒤 기존 배포를 계속 보면 같은 증상이 나온다. Vercel 환경변수 문서에서 현재 프로젝트의 환경 범위를 확인한다.

특히 NEXT_PUBLIC_ 값은 빌드 시점에 번들에 들어갈 수 있다. 그래서 대시보드에서 값을 저장한 뒤에는 값을 저장한 환경으로 새 배포를 만들고, 그 배포 URL에서 다시 확인한다. 브라우저 캐시를 의심하기 전에 배포 로그의 환경과 빌드 시간을 먼저 맞추면 원인을 더 빨리 줄일 수 있다. 예전 화면이 계속 보일 때는 Git 브랜치부터 확인하는 Vercel 배포 점검 순서도 함께 확인할 수 있다.

배포 전에 이 네 줄만 남기면 AI 수정도 검증할 수 있다

다음 체크는 값을 실제로 적지 않고도 AI 수정과 배포 설정을 함께 검증하는 방법이다.

1. 이 값이 브라우저에 보여도 되는 공개값인지 한 줄로 적는다.
2. 값을 읽는 파일이 클라이언트 코드인지 서버 코드인지 확인한다.
3. 공개값일 때만 NEXT_PUBLIC_ 접두사와 코드의 정적 이름을 맞춘다.
4. Vercel의 Development·Preview·Production 중 실제 배포 환경을 고르고 새 빌드 URL에서 확인한다.

Tap to zoom

값이 계속 비어 있다고 해서 비밀값을 클라이언트로 옮기지 않는다. 먼저 서버 경계와 배포 환경을 기록한 뒤, 한 번의 새 빌드로 결과를 확인한다. 그 기록이 있으면 AI에게도 "이 값은 브라우저 공개값인가, 어느 환경에 넣었고 어느 URL에서 확인했는가"를 정확히 다시 물을 수 있다.

참고 출처

• Next.js 공식 문서: Environment Variables
• Vercel 공식 문서: Environment Variables

이 글은 AI 코딩과 개발 학습의 일반 정보 제공 목적입니다. 도구, 모델, 커리큘럼, 요금은 버전과 시점에 따라 달라질 수 있으므로 실습이나 도입 전 공식 문서와 최신 릴리스 노트를 확인하세요.