환경 변수와 .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 탭
이렇게 하면 코드에는 비밀이 없고, 실행 환경에서만 안전하게 값을 읽어올 수 있습니다.
📋 30초 요약
-
환경 변수는 API 키, 비밀번호 같은 민감한 정보를 코드와 분리하여 저장하는 방법입니다.
.env파일에KEY=VALUE형식으로 작성하고, 코드에서는process.env.KEY로 읽어옵니다. -
.gitignore에 .env를 반드시 추가하세요. 이걸 빠뜨리면 API 키가 GitHub에 공개되어 과금 사고나 보안 침해가 발생할 수 있습니다. 바이브코딩에서 가장 흔한 실수입니다.
-
배포할 때는 배포 플랫폼(Vercel, Netlify 등)의 환경 변수 설정에 별도로 입력해야 합니다. .env 파일은 여러분의 컴퓨터에만 존재하므로, 서버에는 직접 전달해야 합니다.
바이브코딩으로 프로젝트를 만들고 GitHub에 올리려고 합니다. 다음 중 반드시 확인해야 할 사항은 무엇일까요?
연관 개념
훅 (Hooks) 알아보기
Claude Code가 특정 행동을 하기 전·후에 자동으로 실행되는 명령입니다. 파일 수정 직후 자동 포맷, 커밋 직전 lint 실행 같은 자동 검사·자동 작업을 만들 때 씁니다.
서브에이전트 (Subagents) 알아보기
한 작업의 부분을 따로 나눠 처리하는 보조 에이전트입니다. 주력 에이전트가 작업 전체를 조율하고, 서브에이전트들이 코드 검토, 자료 조사, 테스트 작성 같은 부분 작업을 동시에 처리해 결과를 합칩니다.
Plan Mode (실행 전 검토 단계) 활용하기
Claude Code가 실제로 파일을 수정하기 전에 무엇을 어떻게 바꿀지 계획만 먼저 보여주는 모드입니다. 사용자가 계획을 검토·승인한 뒤에야 실제 변경이 진행됩니다.
관련 인사이트
쉽게 설치하는 코덱스(Codex) CLI 세팅가이드(맥)
맥(Mac)에 OpenAI 코덱스 CLI(Codex CLI)를 처음 설치하는 분을 위해, 터미널 실행부터 Homebrew·Node.js 사전 준비, 본체 설치, ChatGPT 로그인, GPT-5.5 모델 선택까지 단순하게 정리했습니다. 클로드 코드(Claude Code)와의 차이도 마지막에 짧게 짚었습니다.
쉽게 설치하는 코덱스(Codex) CLI 세팅가이드(윈도우)
윈도우 PC에 OpenAI 코덱스 CLI(Codex CLI)를 처음 설치하는 분을 위해, PowerShell 관리자 모드부터 Node.js 준비, 본체 설치, ChatGPT 로그인, GPT-5.5 모델 선택까지 단순하게 정리했습니다. 클로드 코드(Claude Code)와의 차이도 마지막에 짧게 짚었습니다.
쉽게 설치하는 클로드코드 세팅가이드(맥)
맥(Mac)에 클로드 코드(Claude Code)를 처음 설치하는 분을 위해, 터미널 실행부터 Homebrew·Git·Node.js 사전 준비, 본체 설치, 한국어 설정, 첫 작업 시작까지 9단계로 단순하게 정리했습니다.
