이 글은 프론트엔드 배포 오류 체크리스트: Vercel, Vite, Expo 문제 해결의 세부 항목입니다. 전체 설정 흐름과 관련 오류 해결 순서는 대표 허브 글에서 함께 확인할 수 있습니다.
환경변수를 수정했는데 화면이나 API 요청에서는 예전 값이 보이면 재시작 문제인지, 접두사 문제인지, 빌드 시점 문제인지 헷갈립니다.
이 글에서 확인할 내용
아래 섹션 링크를 통해 필요한 내용을 바로 확인할 수 있습니다.
- 환경변수 파일은 프로젝트 루트에 있어야 합니다
- 브라우저에서 쓰는 값은 NEXT_PUBLIC 접두사가 필요합니다
- 개발 서버는 환경변수 변경을 자동 반영하지 않을 수 있습니다
- 빌드 시점에 박힌 값은 다시 빌드해야 바뀝니다
- 배포 환경에서는 로컬 .env.local이 아니라 플랫폼 설정을 봅니다
- 발행 전 마지막 점검 기준
- 실제 작업에서는 재현 조건을 먼저 고정합니다
- 같은 오류가 반복되지 않게 기록할 것
환경변수 파일은 프로젝트 루트에 있어야 합니다
Next.js의 .env.local은 package.json이 있는 프로젝트 루트에 둬야 합니다. src 폴더 안이나 app 폴더 안에 두면 읽히지 않습니다. 변수 이름에 오타가 있거나 공백이 섞여도 값이 기대와 다르게 보일 수 있습니다. 먼저 파일 위치, 변수명, 따옴표, 공백을 확인합니다. 환경변수 문제는 코드보다 파일 위치와 이름에서 시작되는 경우가 많습니다.
브라우저에서 쓰는 값은 NEXT_PUBLIC 접두사가 필요합니다
Next.js에서 서버에서만 쓰는 환경변수와 브라우저에 노출되는 환경변수는 다릅니다. 클라이언트 컴포넌트나 브라우저 코드에서 접근해야 하는 값은 NEXT_PUBLIC_ 접두사가 필요하고, 코드에서는 보통 process.env.NEXT_PUBLIC_NAME처럼 정적으로 참조해야 번들에 포함됩니다. 반대로 비밀 키나 서버 토큰에 NEXT_PUBLIC_을 붙이면 브라우저 번들에 노출될 수 있으므로 위험합니다. API URL처럼 공개되어도 되는 값과 관리자 토큰처럼 숨겨야 하는 값을 먼저 나눕니다.
npm run build
# Vercel 로그의 첫 번째 에러를 로컬에서 재현합니다.개발 서버는 환경변수 변경을 자동 반영하지 않을 수 있습니다
코드를 고치면 핫 리로드가 되지만 환경변수는 개발 서버 시작 시점에 읽히는 값이 많습니다. .env.local을 바꾼 뒤에도 이전 값이 보이면 npm run dev를 완전히 종료하고 다시 시작합니다. 터미널을 여러 개 켜두었다면 실제로 실행 중인 dev 서버가 어느 프로젝트인지도 확인합니다. 간단하지만 이 단계에서 해결되는 경우가 꽤 많습니다.
빌드 시점에 박힌 값은 다시 빌드해야 바뀝니다
NEXT_PUBLIC_ 환경변수는 클라이언트 번들에 포함될 수 있습니다. 이 경우 배포 후 값을 바꿨다고 이미 만들어진 정적 파일이 자동으로 바뀌지 않습니다. 다시 빌드하고 배포해야 새 값이 반영됩니다. 서버 런타임에서 동적으로 읽는 값인지, 정적 생성이나 클라이언트 번들에 들어가 빌드 시점 값으로 굳는 값인지 구분해야 합니다. 특히 Vercel에서는 배포용 Production/Preview 환경변수와 로컬 개발용 Development 환경변수가 서로 다를 수 있습니다.
배포 환경에서는 로컬 .env.local이 아니라 플랫폼 설정을 봅니다
Vercel 배포 환경의 값은 로컬 .env.local이 아니라 Project Settings의 Environment Variables에서 확인합니다. 같은 변수 이름이 Production과 Preview 중 어디에 등록되어 있는지 함께 봐야 하고, 로컬 개발에서 쓰는 Development 값은 별도로 구분합니다. 최종 점검 순서는 파일 위치, 변수 이름, NEXT_PUBLIC_ 여부, dev 서버 재시작, 빌드 재실행, Vercel 환경변수입니다.
공식 문서 기준으로 Next.js는 .env* 파일을 프로젝트 루트에서 로드하고, NEXT_PUBLIC_ 변수는 브라우저 번들에 인라인될 수 있으며, 런타임 환경변수는 서버 실행 시점에서 읽는 값으로 구분해야 합니다. 자세한 기준은 Next.js Environment Variables 문서와 Vercel Environment Variables 문서를 함께 확인하면 좋습니다.
발행 전 마지막 점검 기준
값이 계속 바뀌지 않는다면 먼저 문제가 나는 위치를 좁힙니다. 로컬 개발 서버인지, 로컬 빌드인지, Vercel Preview인지, Production 배포인지에 따라 확인할 설정이 달라집니다.
.env.local이package.json과 같은 프로젝트 루트에 있는가?- 브라우저에서 읽는 값에는
NEXT_PUBLIC_접두사가 붙어 있는가? - 환경변수 수정 뒤 개발 서버를 완전히 재시작했는가?
- 클라이언트 번들에 들어간 값이라면 다시 빌드하고 배포했는가?
- Vercel의 Production, Preview, Development 환경에 같은 이름의 변수가 등록되어 있는가?
실제 작업에서는 재현 조건을 먼저 고정합니다
같은 코드라도 로컬 개발 서버, 로컬 빌드, Vercel Preview, Production 배포에서 다르게 보일 수 있습니다. 먼저 어느 환경에서 문제가 나는지 적고, 같은 조건으로 다시 실행해 본 뒤 원인을 좁히는 편이 빠릅니다.
환경변수 문제라면 수정 전후 값을 직접 출력하기보다, 변수 이름과 실행 위치를 확인합니다. 브라우저에서 읽는 값인지 서버에서만 읽는 값인지, 개발 서버 재시작과 재빌드를 했는지, 배포 플랫폼에 같은 이름으로 등록했는지를 순서대로 확인합니다.
같은 오류가 반복되지 않게 기록할 것
문제를 해결한 뒤에는 어떤 환경에서 재현됐는지, 어떤 변수 이름을 수정했는지, 개발 서버 재시작이나 재빌드를 했는지 남겨둡니다. 팀 프로젝트라면 README나 작업 메모에 Node 버전, 패키지 매니저, 배포 플랫폼의 환경변수 위치도 함께 적어두는 것이 좋습니다.
환경변수 문제는 값 자체보다 어디에서 언제 읽히는지가 중요합니다. 수정 전후 조건을 남겨두면 다음 배포나 다음 로컬 실행에서 같은 증상이 나와도 더 빨리 원인을 좁힐 수 있습니다.
“Next.js 환경변수 적용 오류 해결: .env.local을 바꿨는데 값이 안 바뀔 때”에 대한 4개의 생각