.env 파일 완전 가이드 - 비개발자가 반드시 알아야 할 환경 변수 설정과 보안

.env 파일 완전 가이드 — 비개발자가 반드시 알아야 할 환경 변수 설정과 보안

.env 파일이 왜 필요한가

💭 이미 알고 있는 것부터

이전 글들에서 배웠습니다. .env 파일은 API 키를 코드에 직접 쓰지 않기 위한 공간이고, GitHub에 올리면 절대 안 된다고요.

그런데 실제로 바이브 코딩을 하다 보면 이런 순간들이 옵니다.

".env랑 .env.local이 둘 다 있는데 어디에 넣어야 하지?"

"AI가 NEXT_PUBLIC_을 붙이라는데, 붙여야 하는 건지 말아야 하는 건지 모르겠어."

"로컬에서는 잘 됐는데 Vercel에 배포하니까 갑자기 안 된다. 환경 변수 문제인 것 같은데..."

이 글은 .env의 기본 개념을 이미 아는 분들을 위한 심화 가이드입니다. 파일 종류별 차이, NEXT_PUBLIC_ 이해, Vercel 배포 설정, 그리고 API 키가 실수로 노출됐을 때 즉시 해야 할 것까지 다룹니다.

.env 파일 종류 — 어디에 뭘 써야 하는가

프로젝트를 보면 .env 관련 파일이 여러 개 있을 수 있습니다. 각각이 어떤 상황에서 적용되는지 알면 어느 파일에 키를 넣어야 할지 헷갈리지 않습니다.

파일 이름	언제 적용되나	GitHub 업로드	용도
`.env`	모든 환경 (공통 기본값)	❌ 올리지 않음	모든 환경에서 공통으로 쓰는 값. 민감하지 않은 기본 설정
`.env.local`	로컬(내 컴퓨터)만	❌ 절대 올리지 않음	내 컴퓨터에서만 쓰는 API 키. .env보다 우선순위 높음
`.env.development`	개발 환경(npm run dev)만	⚠️ 상황에 따라	개발 중에만 적용되는 설정 (예: 테스트용 DB 주소)
`.env.production`	배포 환경만	⚠️ 상황에 따라	실제 서비스 배포 시 적용. Vercel 환경 변수가 이를 대체
`.env.example`	적용 안 됨 (예시 파일)	✅ 올려도 됨	어떤 키가 필요한지 보여주는 템플릿. 실제 값 없이 이름만

💡 실제로 가장 많이 쓰는 조합

바이브 코딩 입문 단계에서 가장 자주 쓰는 조합은 .env.local (로컬 개발용) 하나입니다. Vercel 배포 시에는 대시보드에서 직접 환경 변수를 설정하므로 .env.production 파일을 따로 만들 필요가 없습니다. "어디에 넣어야 할지 모르겠다"면 .env.local에 넣으면 됩니다.

.env 파일 종류별 차이 — .env, .env.local, .env.development, .env.production 적용 환경 비교

NEXT_PUBLIC_ — 이 접두사가 붙는 이유

Next.js에서 환경 변수를 쓰다 보면 AI가 어떤 변수에는 NEXT_PUBLIC_을 붙이고 어떤 변수에는 안 붙입니다. 규칙이 있습니다.

🌐 NEXT_PUBLIC_ 붙이는 것

브라우저(클라이언트)에서도 읽어야 하는 값

지도 API 공개 키, Supabase URL, 공개 사이트 URL 등

⚠️ 브라우저에서 누구나 볼 수 있습니다. 완전히 비밀인 값은 여기 넣으면 안 됩니다.

🔒 NEXT_PUBLIC_ 안 붙이는 것

서버에서만 읽어야 하는 민감한 값

OpenAI API 키, Supabase 서비스 롤 키, 데이터베이스 비밀번호 등

✅ 서버에서만 접근. 브라우저에 절대 노출되지 않습니다.

        # ✅ 브라우저에서 접근 가능 (NEXT_PUBLIC_ 붙임)

        NEXT_PUBLIC_SUPABASE_URL=https://abcdef.supabase.co

        NEXT_PUBLIC_KAKAO_MAP_KEY=abc123xyz

        # 🔒 서버에서만 접근 (NEXT_PUBLIC_ 없음)

        SUPABASE_SERVICE_ROLE_KEY=eyJhbGci...

        OPENAI_API_KEY=sk-proj-...

        DATABASE_URL=postgresql://...

💡 헷갈릴 때 판단 기준

모르겠으면 AI에게 "이 API 키가 브라우저에서 접근해야 하는 값인지, 서버에서만 써야 하는 값인지 알려줘"라고 물어보세요. AI가 NEXT_PUBLIC_을 붙여야 하는지 아닌지 알려줍니다. 일반적으로 OpenAI, Anthropic 같은 AI API 키는 절대 NEXT_PUBLIC_을 붙이면 안 됩니다.

서비스별 실제 .env 작성 예시

바이브 코딩에서 가장 자주 연결하는 서비스들의 실제 .env 작성 예시입니다. AI가 알려주는 형식과 비교하면서 참고하세요.

🗄️ Supabase 데이터베이스 · 인증

Supabase 프로젝트 대시보드 → Settings → API에서 키를 복사합니다.

            # Supabase URL — 브라우저에서도 접근 (NEXT_PUBLIC_)

            NEXT_PUBLIC_SUPABASE_URL=https://프로젝트ID.supabase.co

            # anon key — 브라우저에서 접근 (공개 가능한 키)

            NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6...

            # service role key — 서버만 (절대 NEXT_PUBLIC_ 붙이지 않음)

            SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6...

🤖 OpenAI AI 기능 연결

platform.openai.com → API Keys에서 새 키를 발급합니다. 발급 직후 한 번만 표시되므로 바로 복사하세요.

            # OpenAI API 키 — 서버에서만 (절대 NEXT_PUBLIC_ 금지)

            OPENAI_API_KEY=sk-proj-abcdefghijklmnop...

            # 모델 지정 (선택사항)

            OPENAI_MODEL=gpt-4o

⚠️ OpenAI 키에 NEXT_PUBLIC_을 붙이면 브라우저에서 키가 노출됩니다. 반드시 서버 전용으로만 씁니다.

🗺️ 카카오맵 / 네이버 지도 지도 API

지도 API는 브라우저에서 직접 렌더링하므로 NEXT_PUBLIC_을 붙여야 합니다.

            # 카카오맵 — 브라우저에서 렌더링 (NEXT_PUBLIC_ 필수)

            NEXT_PUBLIC_KAKAO_MAP_KEY=abc123xyz456...

            # 네이버 지도

            NEXT_PUBLIC_NAVER_MAP_CLIENT_ID=naver_client_id_here

🔔 .env.example 만들기 팀 공유용 · GitHub 업로드 가능

실제 값 없이 어떤 키가 필요한지만 보여주는 템플릿 파일입니다. GitHub에 올려도 됩니다. 협업하거나 나중에 다른 컴퓨터에서 셋업할 때 유용합니다.

            # .env.example — 실제 값 없이 키 이름만 (GitHub에 올려도 됨)

            NEXT_PUBLIC_SUPABASE_URL=여기에_supabase_url_입력

            NEXT_PUBLIC_SUPABASE_ANON_KEY=여기에_anon_key_입력

            OPENAI_API_KEY=여기에_openai_key_입력

Vercel 배포 환경 변수 설정하는 법

로컬의 .env.local 파일은 내 컴퓨터에서만 작동합니다. Vercel에 배포하면 이 파일이 자동으로 올라가지 않습니다. 배포 환경에서도 환경 변수가 필요하면 Vercel 대시보드에서 직접 설정해야 합니다.

vercel.com에서 프로젝트로 이동

대시보드에서 배포된 프로젝트를 클릭합니다.

Settings → Environment Variables 클릭

상단 탭에서 Settings를 선택하고 왼쪽 메뉴에서 Environment Variables를 클릭합니다.

Key와 Value 입력

Key 칸에 변수 이름(예: OPENAI_API_KEY), Value 칸에 실제 키 값을 입력합니다. NEXT_PUBLIC_도 그대로 입력합니다.

환경 선택 후 Save

Production, Preview, Development 중 적용할 환경을 체크합니다. 대부분 Production만 체크하면 됩니다. Save 클릭.

반드시 재배포(Redeploy)

환경 변수를 추가한 후에는 Deployments 탭에서 최근 배포를 클릭하고 Redeploy를 눌러야 합니다. 재배포하지 않으면 변수가 적용되지 않습니다.

💡 Vercel에서 환경 변수가 작동 안 할 때 체크리스트

① 변수를 추가하고 재배포(Redeploy)했는지 확인. ② 변수 이름에 오타가 없는지 확인 (대소문자 구분). ③ NEXT_PUBLIC_ 여부가 코드와 Vercel 설정에서 일치하는지 확인. ④ 그래도 안 되면 에러 메시지를 AI에게 붙여넣어 물어보세요.

API 키가 노출됐을 때 — 즉시 해야 할 것

실수로 API 키를 GitHub에 올렸거나, .gitignore 설정을 잊고 커밋했을 경우 즉시 행동해야 합니다. GitHub에서 파일을 삭제해도 이미 공개된 커밋 히스토리에 키가 남아 있습니다. 삭제만으로는 부족합니다.

🚨 API 키 노출 시 즉시 행동 순서

1 해당 API 키를 즉시 폐기(Revoke)합니다. GitHub에서 지우는 것보다 먼저입니다. 이미 누군가 봤을 수 있기 때문입니다.
2 서비스별 키 폐기 위치: OpenAI → platform.openai.com → API Keys → 해당 키 Delete. Supabase → 프로젝트 Settings → API → 키 재생성. Anthropic → console.anthropic.com → API Keys.
3 새 키를 발급받아 .env.local에 교체합니다. 파일에서 기존 키를 삭제하고 새 키를 붙여넣습니다.
4 .gitignore에 .env.local이 포함됐는지 확인합니다. AI에게 "이 프로젝트 .gitignore에 .env 관련 파일 모두 추가해줘"라고 요청합니다.
5 Vercel 환경 변수도 새 키로 교체합니다. 이전 섹션을 참고해 대시보드에서 업데이트 후 재배포합니다.
6 (선택) GitHub 커밋 히스토리에서 키를 제거합니다. 복잡한 작업이므로 AI에게 "git filter-branch로 커밋 히스토리에서 .env 파일 제거하는 방법"을 물어보거나, 저장소를 새로 만드는 것도 방법입니다.

💡 요금 폭탄 방지 — OpenAI 사용 한도 설정

OpenAI 키가 노출되면 다른 사람이 무단으로 사용할 수 있습니다. platform.openai.com → Settings → Limits에서 월별 사용 한도(Usage Limit)를 설정해두면 피해를 최소화할 수 있습니다. 바이브 코딩을 시작할 때부터 한도를 설정해두는 것을 강력히 추천합니다.

AI에게 .env 설정 요청하는 올바른 방법

AI에게 .env 관련 작업을 요청할 때 주의할 점이 있습니다. 실제 API 키 값을 AI 대화창에 붙여넣지 마세요. Claude나 ChatGPT에 입력한 내용은 해당 서비스 서버를 거칩니다.

❌ 이렇게 하지 마세요

내 .env 파일에 이렇게 되어 있어: OPENAI_API_KEY=sk-proj-abc123xyz456... 이게 왜 안 되는지 봐줘

✅ 이렇게 요청하세요

OPENAI_API_KEY가 .env.local에 있는데 Vercel에서 인식이 안 됩니다. 실제 키 값은 올바른 형식입니다. Vercel 환경 변수 설정이 제대로 됐는지 확인하는 방법 알려줘.

키 값 없이 문제 상황만 설명해도 AI는 충분히 도움을 줄 수 있습니다. 아래는 상황별 올바른 요청 방식입니다.

✅ 환경 변수 설정 요청

이 프로젝트에 Supabase를 연결하려고 해. .env.local 파일에 어떤 변수를 넣어야 하고, NEXT_PUBLIC_을 붙여야 하는 것과 붙이면 안 되는 것을 구분해서 알려줘. 실제 키 값은 내가 직접 입력할게.

✅ .gitignore 설정 요청

이 프로젝트의 .gitignore 파일에 .env 관련 파일이 모두 포함됐는지 확인하고, 빠진 것이 있으면 추가해줘.

📖 이 시리즈 함께 읽기
관련 글 → [[비개발자가 바이브 코딩을 시작하면 GitHub를 가장 먼저 배워야 하는 이유]] — .gitignore와 보안 기초 관련 글 → [[VS Code 폴더 구조 읽는 법 — 비개발자가 알아야 할 것만 골라서]] — 프로젝트 내 .env 파일 위치

📌 핵심 정리

바이브 코딩 입문 단계에서 쓰는 .env 파일은 주로 .env.local 하나입니다. 민감한 API 키는 여기에 넣고, Vercel 배포 시에는 대시보드에서 별도로 설정합니다.
NEXT_PUBLIC_은 브라우저에서도 접근해야 하는 값에만 붙입니다. OpenAI, Supabase Service Role Key 같은 완전 비밀 키에는 절대 붙이지 않습니다.
Vercel에 배포했는데 환경 변수가 작동하지 않는다면 대시보드 Settings → Environment Variables에서 직접 추가하고 Redeploy를 눌러야 합니다.
API 키가 GitHub에 노출됐다면 즉시 해당 서비스에서 키를 폐기(Revoke)하고 새 키를 발급받아야 합니다. GitHub에서 파일을 지우는 것만으로는 부족합니다.
AI에게 .env 관련 도움을 요청할 때 실제 키 값을 대화창에 붙여넣지 마세요. 키 없이 문제 상황만 설명해도 충분히 도움을 받을 수 있습니다.

❓ 자주 묻는 질문

.env와 .env.local의 차이가 뭔가요?

.env는 모든 환경(개발·배포)에서 공통으로 적용되는 기본값을 담습니다. .env.local은 내 컴퓨터(로컬)에서만 적용되는 값으로, .env보다 우선순위가 높습니다. 민감한 API 키는 .env.local에 넣는 것이 권장됩니다. 두 파일 모두 .gitignore에 포함해야 GitHub에 올라가지 않습니다. 바이브 코딩 입문 단계에서는 .env.local 하나만 쓰면 됩니다.

NEXT_PUBLIC_을 변수 이름 앞에 붙이는 이유가 뭔가요?

Next.js에서 환경 변수는 기본적으로 서버에서만 읽을 수 있습니다. 그런데 지도 API 키나 Supabase URL처럼 브라우저(클라이언트)에서도 접근해야 하는 값은 변수 이름 앞에 NEXT_PUBLIC_을 붙여야 합니다. 단, NEXT_PUBLIC_이 붙은 변수는 브라우저에서 누구나 볼 수 있으므로 완전히 비밀로 해야 하는 값(서버 전용 API 키 등)에는 붙이지 않습니다.

실수로 API 키를 GitHub에 올렸을 때 어떻게 해야 하나요?

즉시 해당 API 키를 폐기(revoke)해야 합니다. 키를 GitHub에서 삭제해도 이미 공개된 이상 누군가 볼 수 있습니다. OpenAI라면 platform.openai.com에서, Supabase라면 프로젝트 설정에서 키를 재발급받으세요. 그 후 새 키를 .env.local 파일에 넣고, .gitignore에 .env.local이 포함됐는지 반드시 확인하세요. Vercel 환경 변수도 새 키로 교체해야 합니다.

Vercel에 배포했는데 환경 변수가 작동하지 않을 때 어떻게 하나요?

로컬의 .env.local 파일은 Vercel에 자동으로 올라가지 않습니다. Vercel 대시보드에서 직접 설정해야 합니다. Vercel 프로젝트 페이지 → Settings → Environment Variables 메뉴에서 키와 값을 입력하면 됩니다. 추가 후 반드시 재배포(Redeploy)를 해야 적용됩니다. 변수 이름에 오타가 없는지, NEXT_PUBLIC_ 여부가 코드와 일치하는지도 확인하세요.

지금 .gitignore를 열어보세요

.env.local이 포함되어 있는지 확인하세요.
없다면 AI에게 "이 프로젝트 .gitignore에
.env 관련 파일 모두 추가해줘"라고 요청하세요.

🚀 Vercel 환경 변수 설정하기