Next.js 환경변수 undefined, 배포 직전 3분 점검 5가지

AI가 만들어 준 Next.js 화면이 거의 완성됐는데 API 주소만 undefined로 찍히면 초보자는 바로 코드를 다시 맡기고 싶어집니다. 하지만 환경변수 문제는 코드 전체를 고치는 일이 아닐 때가 많습니다. 파일 위치가 틀렸거나, 변수 이름 한 글자가 다르거나, 브라우저에서 읽어야 하는 값에 NEXT_PUBLIC_ 접두사가 없거나, 개발 서버를 재시작하지 않은 경우가 많습니다.

Next.js 환경변수가 undefined로 나올 때 확인하는 로컬 파일과 배포 환경

nextjs.org의 Next.js 공식 문서는 .env* 파일의 값을 process.env로 로드한다고 설명합니다. nodejs.org의 Node.js 문서도 환경변수를 다루는 기본 API가 process.env라고 설명합니다. 그래서 첫 판단은 단순합니다. 값이 undefined라면 AI에게 "전체를 다시 만들어 주세요"라고 하기 전에, 지금 코드가 읽는 이름과 실제 환경에 들어 있는 이름이 같은지부터 봐야 합니다.

첫 30초에는 .env.local 위치와 이름을 봅니다

가장 먼저 파일 이름을 봅니다. 로컬 개발용 파일은 보통 프로젝트 루트의 .env.local에 둡니다. app 폴더 안이나 src 폴더 안에 넣으면 코드가 맞아도 값이 안 들어온 것처럼 보일 수 있습니다. 파일 이름도 .env.local.txt가 아니어야 합니다.

다음으로 코드가 읽는 이름과 파일에 적은 이름을 그대로 비교합니다.

NEXT_PUBLIC_API_URL=https://api.example.com

const apiUrl = process.env.NEXT_PUBLIC_API_URL;

이 둘은 한 글자까지 같아야 합니다. NEXT_PUBLIC_APIURL, NEXT_PUBLIC_API_URLS, NEXT_PUBLIC_API_URL 처럼 빠진 밑줄, 붙은 복수형, 뒤쪽 공백이 있으면 초보자 눈에는 거의 같아 보여도 다른 값입니다.

이 단계에서 AI에게는 이렇게 묻습니다.

Next.js 환경변수가 undefined로 나옵니다.
아래 .env.local 값과 코드에서 읽는 process.env 이름이 한 글자까지 같은지 비교해 주세요.
코드 전체를 바꾸지 말고 이름 불일치만 찾아 주세요.

.env.local:
[붙여넣기]

관련 코드:
[붙여넣기]

브라우저 화면에서 쓰는 값은 NEXT_PUBLIC_을 확인합니다

Next.js에서 서버에서만 쓰는 값과 브라우저 화면에서 쓰는 값은 다르게 다뤄야 합니다. nextjs.org의 환경변수 문서와 Server/Client Components 문서는 브라우저에 노출할 값에는 NEXT_PUBLIC_ 접두사가 필요하다고 설명합니다. 반대로 API 키나 비밀 토큰처럼 공개되면 안 되는 값은 이 접두사를 붙이면 안 됩니다.

초보자가 자주 겪는 상황은 이렇습니다.

const apiUrl = process.env.API_URL;

이 코드가 클라이언트 컴포넌트나 브라우저에서 실행되는 코드에 있으면 값이 비어 보일 수 있습니다. 브라우저에 보여도 되는 공개 API 주소라면 아래처럼 이름을 맞춥니다.

NEXT_PUBLIC_API_URL=https://api.example.com

const apiUrl = process.env.NEXT_PUBLIC_API_URL;

단, 서비스 비밀키, 관리자 토큰, 데이터베이스 비밀번호는 NEXT_PUBLIC_로 바꾸지 않습니다. 그런 값은 서버 코드, API route, server action처럼 서버에서만 읽는 위치로 옮겨야 합니다. 여기서 중요한 판단은 "undefined를 없애기 위해 모든 변수에 접두사를 붙이는 것"이 아니라 "브라우저에 공개해도 되는 값인지 먼저 나누는 것"입니다.

값을 고친 뒤에는 개발 서버를 다시 켭니다

.env.local을 고쳤는데도 계속 undefined로 보이면 개발 서버를 재시작합니다. Next.js가 환경변수를 읽는 시점과 브라우저 화면이 새로 고침되는 시점이 항상 같지는 않습니다. 초보자는 파일만 저장하고 화면만 새로고침한 뒤 "아직 안 됩니다"라고 생각하기 쉽습니다.

로컬에서는 아래 순서로 봅니다.

# 실행 중인 dev server를 멈춘 뒤
npm run dev

또는 프로젝트가 다른 명령을 쓰면 package.json의 scripts를 보고 실제 개발 서버 명령을 다시 실행합니다.

재시작 뒤에는 값 전체를 화면에 오래 노출하지 말고, 문제 확인용으로만 짧게 확인합니다.

console.log("API URL exists:", Boolean(process.env.NEXT_PUBLIC_API_URL));

실제 주소나 토큰을 그대로 콘솔에 찍는 습관은 피하는 편이 좋습니다. 특히 배포 환경에서는 로그가 남을 수 있으므로 Boolean(...)처럼 존재 여부만 확인하는 방식이 안전합니다.

Vercel 배포에서는 Production과 Preview 값을 따로 봅니다

로컬에서는 되는데 배포에서만 undefined가 나오면 코드보다 배포 환경을 봅니다. vercel.com의 Vercel 문서는 환경변수가 소스 코드 밖에서 설정되는 key-value 값이며 환경에 따라 달라질 수 있다고 설명합니다. 그래서 Development, Preview, Production 중 어디에 값이 들어 있는지 봐야 합니다.

배포 직전에는 이 순서로 확인합니다.

Vercel 프로젝트의 Environment Variables에 같은 이름이 있는지 봅니다.
지금 배포하려는 환경이 Production인지 Preview인지 확인합니다.
변수 이름이 로컬 .env.local과 같은지 비교합니다.
값을 추가하거나 바꿨다면 다시 배포합니다.
공개되면 안 되는 값에 NEXT_PUBLIC_가 붙어 있지 않은지 확인합니다.

Vercel CLI를 쓰는 팀이라면 Vercel의 Environments 문서에 나온 것처럼 vercel env pull로 프로젝트 환경변수를 로컬로 가져오는 흐름도 쓸 수 있습니다. 다만 초보자 단계에서는 먼저 대시보드에서 "어느 환경에 값이 들어 있는가"를 눈으로 확인하는 편이 덜 헷갈립니다.

AI에게는 원인 후보를 5개로 좁혀 달라고 묻습니다

환경변수 문제를 AI에게 다시 맡길 때도 질문 범위를 좁히면 코드가 크게 흔들리지 않습니다. 아래 템플릿을 그대로 붙여 넣습니다.

Next.js 앱에서 환경변수가 undefined로 나옵니다.
전체 코드를 다시 만들지 말고 원인 후보를 5개 안에서 좁혀 주세요.

상황:
- 로컬/배포 중 어디에서 undefined인지:
- 브라우저 화면/서버 코드 중 어디에서 읽는지:
- 사용 중인 배포 환경:

.env.local 또는 배포 환경 변수 이름:
[값은 가리고 이름만 붙여넣기]

관련 코드:
[process.env를 읽는 부분만 붙여넣기]

확인해 주세요:
1. 파일 위치가 맞는지
2. 변수 이름이 같은지
3. NEXT_PUBLIC_ 접두사가 필요한 위치인지
4. 개발 서버 재시작이 필요한지
5. Vercel 환경 설정이 빠졌는지

수정이 필요하다면 최소 변경 파일과 이유만 알려 주세요.

이 질문은 AI에게 새 구조를 만들게 하는 요청이 아닙니다. 지금 멈춘 원인을 분류하게 만드는 요청입니다. 코딩사관학교 초보자에게 필요한 것은 "더 똑똑한 답변"보다 "AI가 건드릴 범위를 줄이는 질문"입니다.

오늘 저장하기 전 5줄만 채우면 됩니다

환경변수 undefined는 큰 오류처럼 보이지만, 처음 확인할 순서는 좁습니다. 아래 5줄을 채운 뒤에만 AI에게 다시 맡깁니다.

파일 위치:
변수 이름:
브라우저 사용 여부:
서버 재시작 여부:
배포 환경:

예시는 이렇습니다.

파일 위치: 프로젝트 루트 .env.local
변수 이름: NEXT_PUBLIC_API_URL
브라우저 사용 여부: 클라이언트 컴포넌트에서 사용
서버 재시작 여부: npm run dev 재시작 완료
배포 환경: Vercel Production에 같은 이름으로 등록

이 정도로 정리되면 AI도 "환경변수 문제"를 막연하게 보지 않습니다. 파일 위치, 이름, 공개 범위, 재시작, 배포 환경 중 어디가 비어 있는지부터 보게 됩니다. 오늘 배포 직전에 undefined가 보이면 코드를 갈아엎기 전에 이 5줄을 먼저 채우세요.

참고 출처

Next.js Environment Variables: https://nextjs.org/docs/pages/guides/environment-variables
Next.js Missing Env Value: https://nextjs.org/docs/messages/missing-env-value
Next.js Server and Client Components: https://nextjs.org/docs/app/getting-started/server-and-client-components
Vercel Environment Variables: https://vercel.com/docs/environment-variables
Vercel Environments: https://vercel.com/docs/deployments/environments
Node.js Environment Variables: https://nodejs.org/api/environment_variables.html

Next.js 배포 직전 환경변수 undefined 3분 점검 5가지