본문 바로가기
카테고리 없음

Vercel 환경변수 적용 오류? 캐시부터 NEXT_PUBLIC까지 완벽 가이드

tofujoy 2025. 8. 31. 12:58

 

Vercel을 이용해 Next.js, React, Node 프로젝트를 배포하다 보면 가장 흔하게 맞닥뜨리는 난관이 있습니다. 바로 환경변수(Environment Variables)가 제대로 적용되지 않는 문제죠. 로컬에서는 잘 되던 API Key나 DB 연결 정보가 배포 후에는 undefined로 찍히거나, 심지어 500 에러를 뿜어내는 상황이 발생합니다.

이 글은 단순한 FAQ 모음집이 아니라, 왜 이런 오류가 생기는지, 그리고 어떤 과정을 통해 해결할 수 있는지를 체계적으로 정리한 가이드입니다. 특히 많은 분들이 헷갈려하는 캐시 문제와 NEXT_PUBLIC 접두어 이슈까지 완벽하게 짚어드리겠습니다.

✅ 2025년 기준 Vercel 최신 환경에서 직접 테스트한 내용을 바탕으로 작성했습니다. 단순 에러 로그가 아니라, 원인 → 점검 → 해결의 흐름으로 정리했습니다.

1. 환경변수 적용 안 되는 대표적인 상황

  1. 로컬에서는 .env.local로 잘 되는데, Vercel 배포 후 process.env.MY_KEY가 undefined로 찍힘
  2. Vercel 대시보드에 환경변수를 등록했는데도 빌드된 결과물이 못 읽음
  3. Next.js에서 클라이언트 사이드 코드에서 환경변수가 보이지 않음
  4. 배포 후 환경변수를 수정했는데도 즉시 반영되지 않음

위 케이스들은 전부 다 같은 뿌리를 가지고 있습니다. 바로 Vercel의 빌드 방식과 환경변수 노출 범위 때문입니다.

2. Vercel에서 환경변수가 안 먹는 이유

  1. 빌드 타임과 런타임 구분
    • Vercel은 코드를 배포할 때 빌드 단계에서 환경변수를 읽습니다.
    • 따라서 배포 이후 환경변수를 수정하면, 새로 배포(재빌드)를 하지 않는 이상 반영되지 않습니다.
  2. 서버사이드와 클라이언트사이드의 차이
    • process.env.MY_KEY는 서버사이드에서만 접근 가능합니다.
    • 클라이언트(브라우저)에서 쓰고 싶다면 반드시 NEXT_PUBLIC_ prefix를 붙여야 합니다.
// 서버 전용
const secret = process.env.MY_SECRET_KEY;


// 클라이언트 노출 가능
const publicKey = process.env.NEXT_PUBLIC_API_KEY;

 

 

 3. 환경별 분리(Development / Preview / Production)

  • Vercel은 환경변수를 3가지 레벨로 나눕니다.
    • Development (로컬 개발)
    • Preview (Pull Request 등 미리 보기 배포)
    • Production (실제 서비스)
  • Production에 넣어야 하는데 Preview에만 넣은 경우, 실제 배포에는 적용되지 않습니다.

  4. 빌드 캐시

  • 환경변수를 잘못 넣고 빌드했다가 수정했더라도, 캐시 때문에 바로 반영이 안 될 수 있습니다.
  • 이 경우 "Clear Cache & Redeploy"를 눌러야 합니다.

3. 해결 방법 체크리스트

✅ 1) 환경변수 등록 확인하기

  • Vercel Dashboard → Project → Settings → Environment Variables
  • 올바른 환경(Environment: Production/Preview/Development) 선택했는지 확인
  • Key, Value 오타 없는지 확인 (특히 앞뒤 공백!)

✅ 2) NEXT_PUBLIC prefix 여부

  • 클라이언트에서 쓰려면 반드시 NEXT_PUBLIC_ 접두어 붙이기
  • 서버에서만 쓰는 값(DB 비밀번호, Secret Key 등)은 그대로 사용 가능

✅ 3) 재빌드 필수

  • 환경변수 수정 후에는 반드시 "Redeploy" 필요
  • 급할 때는 "Clear Cache & Redeploy"까지 해주면 더 확실

✅ 4) 빌드 로그 확인

  • Vercel Deployments → 특정 배포 → Logs
  • process.env 관련 경고나 undefined 여부 확인

✅ 5) 코드 내 접근 위치 확인

  • 클라이언트에서 process.env.MY_SECRET 접근하면 무조건 undefined
  • API Route나 getServerSideProps에서만 접근 가능

4. 자주 하는 실수 Top 5

  1. .env.local만 믿고 Vercel 대시보드에 환경변수를 안 넣음
  2. NEXT_PUBLIC_ 안 붙이고 클라이언트에서 불러옴
  3. Production이 아니라 Preview에만 환경변수를 넣음
  4. 환경변수 수정 후 재배포 안 함
  5. 서버 전용 비밀키를 실수로 NEXT_PUBLIC_ 붙여서 노출시킴 (보안 문제!)

5. 고급 팁: 안전하게 관리하는 방법

  1. Secret Manager 연동
    • AWS Secret Manager, Google Secret Manager와 연동하면 더 안전하게 관리 가능
  2. 모노레포 구조
    • Turborepo 등 모노레포일 경우 환경변수 공유 범위를 꼭 확인
  3. Runtime Config 활용
    • Next.js 13 이후부터는 Edge Functions, Middleware에서 env를 쓰려면 runtime config 방식도 고려해야 함

6. 정리

  • Vercel 환경변수는 빌드 타임/런타임, 클라이언트/서버, 환경 구분 때문에 꼬이는 경우가 많음
  • 클라이언트에 쓰려면 NEXT_PUBLIC_ 접두어 필수
  • 수정 후에는 항상 재배포
  • Production/Preview 헷갈리지 않기

환경변수 문제는 대부분 작은 실수에서 비롯됩니다. 위 체크리스트를 순서대로 점검하면 90%는 바로 해결됩니다. 나머지 10%는 빌드 로그와 캐시 문제이니, Clear Cache & Redeploy를 꼭 활용해 보세요.

7. 마무리

이 글이 단순한 "FAQ" 수준이 아니라, 문제의 원리와 해결 과정을 이해하는 데 도움이 되었길 바랍니다. AdSense를 통해서 이 글을 찾아온 분들이라면 아마 절박한 상황일 가능성이 높은데, 이 가이드대로 하면 대부분 해결될 겁니다.

혹시 그래도 안 된다면? 댓글로 상황을 남겨주시면 추가로 케이스별 설루션도 정리해 드리겠습니다. 🚀

티스토리툴바