환경 변수와 .env (Environment Variables)
프로그램이 실행될 때 참조하는 설정값으로, API 키나 비밀번호 같은 민감한 정보를 코드와 분리하여 안전하게 관리하는 방법입니다.
🤔 혹시 이런 경험 있나요?
AI에게 "OpenAI API 연동해줘"라고 했더니, 코드를 만들어주면서 이렇게 말합니다.
".env 파일에
OPENAI_API_KEY=sk-xxxxx를 추가하세요."
.env 파일? 환경 변수? 왜 코드에 직접 안 넣고 따로 파일을 만들라는 걸까요?
이걸 제대로 이해하지 않으면, 바이브코딩으로 만든 프로젝트를 GitHub에 올렸다가 API 키가 전 세계에 공개되는 사고가 벌어질 수 있습니다. 실제로 매우 흔하게 일어나는 일입니다.
🔑 환경 변수, 한마디로 뭘까요?
환경 변수(Environment Variable)는 프로그램이 실행될 때 참조하는 외부 설정값입니다.
코드 안에 직접 적지 않고, 별도의 장소에 보관해두는 비밀 메모장 같은 것입니다. 프로그램이 실행되면 "비밀 메모장에서 이 값을 읽어와"라고 요청하는 방식으로 작동합니다.
🔐 사물함 비밀번호와 같습니다
학교 사물함을 생각해보세요.
- 나쁜 방법: 사물함 비밀번호를 사물함 문 앞에 포스트잇으로 붙여놓는 것 → 코드에 API 키를 직접 적는 것
- 좋은 방법: 비밀번호를 자기 지갑에 따로 보관하는 것 → .env 파일에 API 키를 저장하는 것
두 경우 모두 사물함을 열 수 있지만, 포스트잇 방식은 지나가는 누구나 비밀번호를 볼 수 있습니다.
📄 .env 파일이란?
.env는 환경 변수를 모아놓은 파일입니다. 프로젝트 폴더의 최상위에 만들며, 형식은 매우 간단합니다.
# .env 파일 예시
OPENAI_API_KEY=sk-abc123def456
DATABASE_URL=postgresql://user:password@localhost:5432/mydb
NEXT_PUBLIC_SITE_URL=https://mysite.com코드에서는 이렇게 사용합니다.
// 코드에서 환경 변수 읽기
const apiKey = process.env.OPENAI_API_KEY;이렇게 하면 코드에는 비밀번호가 전혀 남지 않습니다. .env 파일만 안전하게 관리하면 됩니다.
⚠️ .gitignore가 왜 중요한가요?
바이브코딩의 가장 흔한 보안 사고는 이런 순서로 일어납니다.
- AI가 .env 파일을 만들라고 안내합니다.
- API 키를 .env에 저장합니다.
git add .→git commit→git push를 합니다.- .env 파일까지 GitHub에 올라갑니다.
- 전 세계 누구나 여러분의 API 키를 볼 수 있게 됩니다.
이걸 방지하는 것이 .gitignore 파일입니다.
# .gitignore 파일에 이 한 줄을 추가하세요
.env이렇게 하면 git이 .env 파일을 무시해서, GitHub에 올라가지 않습니다.
중요: 대부분의 프로젝트 템플릿(create-next-app 등)은 .gitignore에 .env가 이미 포함되어 있습니다. 하지만 반드시 확인하세요. AI가 만든 프로젝트에서 .gitignore가 빠져있는 경우도 있습니다.
🛠️ 바이브코딩에서 자주 만나는 환경 변수
| 환경 변수 | 용도 | 예시 |
|---|---|---|
OPENAI_API_KEY | AI API 호출 | sk-abc123... |
DATABASE_URL | 데이터베이스 연결 | postgresql://... |
NEXTAUTH_SECRET | 인증 암호화 키 | my-secret-key |
NEXT_PUBLIC_* | 브라우저에서도 사용 가능한 값 | 사이트 URL 등 |
주의:
NEXT_PUBLIC_으로 시작하는 환경 변수는 브라우저에서도 보입니다. 여기에 비밀 키를 넣으면 안 됩니다.
💡 실수를 방지하는 체크리스트
바이브코딩으로 프로젝트를 만들 때, 이 체크리스트를 따르세요.
- 프로젝트 시작 시:
.env파일이.gitignore에 포함되어 있는지 확인 - API 키 입력 시: 코드 파일이 아닌
.env파일에만 입력 - GitHub에 올리기 전:
git status로 .env가 추적 목록에 없는지 확인 - 이미 올려버렸다면: API 키를 즉시 재발급하고, 이전 키를 폐기
- 배포할 때: Vercel, Netlify 등 배포 플랫폼의 환경 변수 설정에 별도로 입력
🚀 배포할 때 환경 변수는 어떻게 하나요?
.env 파일은 여러분의 컴퓨터에만 존재합니다. 프로젝트를 Vercel이나 Netlify에 배포할 때는 배포 플랫폼의 대시보드에서 환경 변수를 별도로 설정해야 합니다.
- Vercel: Settings → Environment Variables
- Netlify: Site settings → Environment variables
- Railway: Variables 탭
이렇게 하면 코드에는 비밀이 없고, 실행 환경에서만 안전하게 값을 읽어올 수 있습니다.
💼 환경 변수가 문제의 원인이 되는 순간들
공개 저장소에 키를 올려버렸을 때
프로젝트를 GitHub 공개 저장소에 올린 직후, OpenAI에서 "당신의 API 키가 노출되었습니다"라는 메일을 받는 경우가 실제로 있습니다. 봇들이 공개 저장소를 자동으로 훑으며 키를 수집하기 때문에, 노출된 키는 몇 분 안에 악용될 수 있습니다. 이때는 키를 코드에서 지우는 것으로는 부족하고, 즉시 재발급해서 이전 키를 폐기해야 합니다.
로컬에서는 되는데 배포하면 안 될 때
내 컴퓨터에서는 잘 돌아가던 AI 기능이 배포 후에 "API key not found" 에러를 냅니다. .env 파일은 내 컴퓨터에만 있고 GitHub을 거쳐 배포 서버로 전달되지 않기 때문입니다. Vercel 대시보드의 환경 변수 설정에 같은 값을 등록하면 해결됩니다.
다른 컴퓨터에서 프로젝트를 열었을 때
회사 컴퓨터에서 작업하던 프로젝트를 집에서 내려받아 실행하면 바로 에러가 납니다. .env가 GitHub에 올라가지 않으니, 새 컴퓨터에는 환경 변수가 하나도 없는 상태이기 때문입니다. 그래서 실무에서는 값을 비운 .env.example 파일을 함께 올려서, 어떤 변수가 필요한지 목록만 공유하는 방식을 씁니다. 인증에 쓰이는 비밀 키들도 같은 방식으로 관리합니다.
📋 30초 요약
-
환경 변수는 API 키, 비밀번호 같은 민감한 정보를 코드와 분리하여 저장하는 방법입니다.
.env파일에KEY=VALUE형식으로 작성하고, 코드에서는process.env.KEY로 읽어옵니다. -
.gitignore에 .env를 반드시 추가하세요. 이걸 빠뜨리면 API 키가 GitHub에 공개되어 과금 사고나 보안 침해가 발생할 수 있습니다. 바이브코딩에서 가장 흔한 실수입니다.
-
배포할 때는 배포 플랫폼(Vercel, Netlify 등)의 환경 변수 설정에 별도로 입력해야 합니다. .env 파일은 여러분의 컴퓨터에만 존재하므로, 서버에는 직접 전달해야 합니다.
이 글이 도움이 되셨다면 공유해 주세요
메신저로 바로 보내거나 링크를 복사할 수 있습니다.
바이브코딩으로 프로젝트를 만들고 GitHub에 올리려고 합니다. 다음 중 반드시 확인해야 할 사항은 무엇일까요?
이어서 배우면 좋은 개념
터미널과 CLI (Terminal & CLI)
컴퓨터에게 텍스트 명령어를 입력해서 작업을 수행하는 도구입니다. AI 코딩 도구가 '이 명령어를 실행하세요'라고 할 때 사용하는 바로 그 검은 화면입니다.
배포 (Deployment)
내 컴퓨터에서만 돌아가던 프로젝트를 인터넷에 올려서 누구나 접속할 수 있게 만드는 과정입니다.
인증과 보안 (Authentication & Security)
사용자가 누구인지 확인하고(인증), 허가된 사람만 데이터에 접근할 수 있도록 보호하는(보안) 시스템입니다.
클로드 코드 플랜과 사용량 한도 이해하기
클로드 코드를 쓸 때 요금이 어떻게 매겨지고, 얼마나 쓰면 한도에 걸리는지를 정하는 구조입니다. 구독 플랜은 정해진 사용량이 포함되고, API 방식은 쓴 만큼 토큰 단위로 요금이 붙습니다.
관련 인사이트
- Qwen3.8 27B 로컬 실행 결과: 24GB 맥에서는 CPU로 떨어집니다Qwen3.8 27B는 알리바바 Qwen 팀이 2026년 8월 공개한 Apache 2.0 오픈 웨이트 모델입니다. 메모리 24GB 맥미니 M4 프로에 직접 설치해 돌려 보니 GPU에 올라가지 못하고 CPU로 실행됐고, 그때 측정한 속도를 그대로 정리했습니다.
- 코덱스 CLI와 클로드 코드 비교 (같은 도구를 만들게 해 봤습니다)코덱스 CLI와 클로드 코드는 터미널에서 파일을 직접 읽고 만드는 코딩 도구입니다. 두 도구에 똑같은 규격서를 주고 같은 도구를 만들게 해서 걸린 시간, 결과물 규모, 안전장치가 어떻게 다른지 측정했습니다.
- 코덱스 CLI 사용법: 초보 블로거를 위한 GEO 인용 검사 도구 만들기 과정코덱스 CLI는 터미널에서 파일을 직접 읽고 만드는 코딩 도구입니다. 빈 폴더에서 시작해 내 글이 AI 답변에 인용되기 쉬운지 확인하는 GEO 점검 도구가 나올 때까지, 시킬 말 전문과 명령을 그대로 정리했습니다.
- 구글 픽셀 11, Qwen3.8, 커서 인수로 본 AI 배포 경쟁AI 배포 경쟁은 같은 모델을 몇 개의 화면에 넣어 두느냐로 우열이 정해지는 경쟁입니다. 2026년 8월 12일부터 15일 사이에 나온 발표 다섯 건을 놓고, 각 회사가 모델을 어디까지 밀어 넣었는지 공식 자료 기준으로 정리했습니다.
- VS Code에서 클로드 코드 실행하기 (윈도우 화면 그대로 따라하기)클로드 코드를 설치했는데 검은 PowerShell 창이 부담스러운 분을 위해, VS Code를 설치하고 그 안 터미널에서 클로드 코드를 실행하는 순서를 화면 그림과 함께 정리했습니다. 승인 질문을 건너뛰는 bypass 모드까지 담았습니다.
- 챗GPT 리눅스 데스크톱 앱 프리뷰 정리: 설치 패키지와 지원 기능챗GPT 리눅스 데스크톱 앱은 오픈AI가 2026년 8월 11일 프리뷰로 공개한 리눅스용 공식 앱으로, ChatGPT와 Work, Codex를 하나의 앱에서 쓸 수 있습니다. 설치 패키지 4종과 테스트된 배포판, 요금 조건에서 확인된 것과 아직 확정되지 않은 것을 구분해 정리했습니다.
