이 글은 프론트엔드 배포 오류 체크리스트: Vercel, Vite, Expo 문제 해결의 세부 항목입니다. 전체 설정 흐름과 관련 오류 해결 순서는 대표 허브 글에서 함께 확인할 수 있습니다.
환경변수를 수정했는데 화면이나 API 요청에서는 예전 값이 보이면 재시작 문제인지, 접두사 문제인지, 빌드 시점 문제인지 헷갈립니다.
환경변수 파일은 프로젝트 루트에 있어야 합니다
Next.js의 .env.local은 이 있는 프로젝트 루트에 둬야 합니다. src 폴더 안이나 app 폴더 안에 두면 읽히지 않습니다. 변수 이름에 오타가 있거나 공백이 섞여도 값이 기대와 다르게 보일 수 있습니다. 먼저 파일 위치, 변수명, 따옴표, 공백을 확인합니다. 환경변수 문제는 코드보다 파일 위치와 이름에서 시작되는 경우가 많습니다.
브라우저에서 쓰는 값은 NEXT_PUBLIC 접두사가 필요합니다
Next.js에서 서버에서만 쓰는 환경변수와 브라우저에 노출되는 환경변수는 다릅니다. 클라이언트 컴포넌트나 브라우저 코드에서 접근해야 하는 값은 NEXT_PUBLIC_ 접두사가 필요합니다. 반대로 비밀 키나 서버 토큰에 NEXT_PUBLIC을 붙이면 브라우저 번들에 노출될 수 있으므로 위험합니다. API URL처럼 공개되어도 되는 값과 관리자 토큰처럼 숨겨야 하는 값을 먼저 나눕니다.
npm run build
# Vercel 로그의 첫 번째 에러를 로컬에서 재현합니다.개발 서버는 환경변수 변경을 자동 반영하지 않을 수 있습니다
코드를 고치면 핫 리로드가 되지만 환경변수는 개발 서버 시작 시점에 읽히는 값이 많습니다. .env.local을 바꾼 뒤에도 이전 값이 보이면 run dev를 완전히 종료하고 다시 시작합니다. 터미널을 여러 개 켜두었다면 실제로 실행 중인 dev 서버가 어느 프로젝트인지도 확인합니다. 간단하지만 이 단계에서 해결되는 경우가 꽤 많습니다.
빌드 시점에 박힌 값은 다시 빌드해야 바뀝니다
NEXT_PUBLIC 환경변수는 클라이언트 번들에 포함될 수 있습니다. 이 경우 배포 후 값을 바꿨다고 이미 만들어진 정적 파일이 자동으로 바뀌지 않습니다. 다시 빌드하고 배포해야 새 값이 반영됩니다. 서버 런타임에서 읽는 값인지, 클라이언트 번들에 들어간 값인지 구분해야 합니다. 특히 Vercel에서는 Preview, Production, Development 환경변수가 각각 다를 수 있습니다.
배포 환경에서는 로컬 .env.local이 아니라 플랫폼 설정을 봅니다
Vercel에 배포할 때 로컬 .env.local 파일은 자동으로 올라가지 않습니다. Project Settings의 Environment Variables에 같은 이름으로 등록해야 합니다. Production 배포에서만 값이 다르다면 환경 구분이 맞는지도 확인합니다. 최종 점검 순서는 파일 위치, 변수 이름, NEXT_PUBLIC 여부, dev 서버 재시작, 빌드 재실행, Vercel 환경변수입니다.
발행 전 마지막 점검 기준
Next.js 환경변수 적용 오류 해결: .env.local을 바꿨는데 값이 안 바뀔 때은 문제 해결형 글이므로 독자가 바로 따라 할 수 있는 순서가 중요합니다. 증상부터 원인을 좁히고로컬에서 재현한 뒤, 설정과 버전 차이를 확인하는 흐름으로 마무리해야 합니다. 기존 글과 겹치는 설명은 길게 반복하지 않고, 현재 글에서는 어떤 기준으로 다음 행동을 선택할지 남기는 것이 좋습니다.
실제 발행 전에는 제목과 포커스 키워드가 너무 넓지 않은지, 본문 이미지가 문제 해결 흐름을 설명하는지, WordPress JSON의 카테고리와 Rank Math 포커스 키워드가 비어 있지 않은지 확인합니다. 이 점검까지 끝나야 단순 초안이 아니라 업로드 가능한 작성본으로 볼 수 있습니다.
실제 작업에서는 재현 조건을 먼저 고정합니다
Next.js 환경변수 적용 오류 해결: .env.local을 바꿨는데 값이 안 바뀔 때 같은 문제 해결형 글은 해결 명령어를 바로 나열하는 것보다 재현 조건을 고정하는 과정이 중요합니다. 같은 코드라도 로컬 개발 서버로컬 빌드, Preview 배포, Production 배포에서 다르게 동작할 수 있기 때문입니다. 독자는 먼저 어느 환경에서 문제가 나는지 표시하고같은 조건으로 다시 실행해본 뒤 원인을 좁혀야 합니다.
문제가 재현되는 조건을 적어두면 수정 후 검증도 쉬워집니다. 예를 들어 환경변수 문제라면 개발 서버 재시작 전후를 나눠 보고, 의존성 문제라면 node_modules를 지운 뒤 lockfile 기준으로 다시 설치합니다. 폼 validation 문제라면 submit 전과 submit 후의 errors 객체를 비교하고, 문제라면 브라우저 Network 탭에서 Origin과 응답 코드를 확인합니다.
또 하나 중요한 점은 임시 우회와 실제 해결을 구분하는 것입니다. 빌드 옵션을 끄거나 강제 설치 옵션을 쓰면 당장 지나갈 수는 있지만, 다음 배포에서 다시 막힐 수 있습니다. 글 본문에서는 빠른 확인 방법을 소개하되, 최종적으로는 설정과 버전을 맞추고 원인을 기록하는 쪽으로 안내해야 합니다.
같은 오류가 반복되지 않게 기록할 것
문제를 해결한 뒤에는 어떤 로그가 원인이었는지, 어떤 설정을 바꿨는지, 어떤 버전 기준으로 맞췄는지 남겨두는 것이 좋습니다. 팀 프로젝트라면 README나 작업 메모에 Node 버전, 패키지 매니저, 환경변수 이름, 배포 플랫폼 설정 위치를 적어두면 다음 사람이 같은 시간을 쓰지 않아도 됩니다.
블로그 글에서도 이 기록 방식이 중요합니다. 독자가 글을 읽고 단순히 “해결했다”에서 끝나는 것이 아니라, 다음에 같은 증상이 나오면 어디부터 확인해야 하는지 기억할 수 있어야 합니다. 그래서 마지막에는 증상, 확인 위치, 수정 방법, 재발 방지 기준을 짧게 다시 연결해주는 구성이 좋습니다.
마지막으로, 해결 후에는 같은 증상이 다시 나왔을 때 바로 비교할 수 있도록 수정 전후 조건을 남깁니다. 어떤 명령어를 실행했는지, 어떤 로그가 바뀌었는지, 어떤 설정값을 수정했는지 적어두면 다음 배포나 다음 설치에서 문제를 더 빨리 좁힐 수 있습니다. 문제 해결 글의 목적은 한 번의 정답을 외우게 하는 것이 아니라, 비슷한 오류를 만났을 때 확인 순서를 떠올리게 만드는 데 있습니다.
이 기준은 혼자 작업할 때보다 팀 프로젝트에서 더 중요합니다. 누군가는 같은 오류를 로컬에서 보고, 다른 사람은 배포 환경에서만 볼 수 있습니다. 그래서 오류 메시지 원문, 실행한 명령어, 사용한 Node/npm 버전, 수정한 설정 파일을 함께 남겨두면 문제 해결 과정이 개인 기억에만 의존하지 않습니다.
작은 설정 차이를 기록하는 습관이 쌓이면 다음 오류에서 확인 시간이 크게 줄어듭니다.
환경변수는 값 자체보다 읽히는 시점이 중요하다는 점을 기억하면 원인을 더 빨리 찾을 수 있습니다.
“Next.js 환경변수 적용 오류 해결: .env.local을 바꿨는데 값이 안 바뀔 때”에 대한 2개의 생각