.env 파일이란? API 키 안전하게 관리하는 방법 — 바이브코딩 필수 가이드 (2026)

바이브코딩으로 프로젝트를 만들다 보면 AI가 “API 키를 .env 파일에 넣으세요”라고 안내하는 경우가 많습니다. 처음 듣는 비전공자 입장에서는 .env 파일이 뭔지, 왜 필요한지, 어떻게 만드는지 막막할 수 있습니다. 이 글에서는 .env 파일의 개념부터 API 키를 안전하게 관리하는 구체적인 방법까지, 한 번 읽으면 바로 적용할 수 있도록 안내합니다.

📄 .env 파일이란 무엇인가

.env 파일은 프로젝트의 비밀 정보를 저장하는 설정 파일입니다. 이름이 점(.)으로 시작하는 이유는 운영체제에서 “숨김 파일”로 취급하기 위해서입니다. 이 파일 안에 API 키, 데이터베이스 주소, 비밀번호 같은 민감한 값을 보관하고, 코드에서는 변수 이름으로만 참조합니다.

쉽게 비유하면, 코드가 “설계도”라면 .env 파일은 “금고”입니다. 설계도(코드)는 누구에게나 보여줄 수 있지만, 금고(.env) 안의 비밀번호는 본인만 알아야 합니다. 코드를 GitHub에 공개하더라도 .env 파일은 올리지 않기 때문에 비밀 정보가 노출되지 않습니다.

🔤 .env 파일 형식

.env 파일의 형식은 매우 단순합니다. 한 줄에 하나씩, 이름=값 형태로 적습니다.

# .env 파일 예시
DATABASE_URL=postgresql://user:password123@localhost:5432/mydb
NEXT_PUBLIC_SUPABASE_URL=https://abcdefg.supabase.co
SUPABASE_SERVICE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
OPENAI_API_KEY=sk-proj-abc123def456...

#으로 시작하는 줄은 주석입니다. 등호(=) 앞뒤에 공백을 넣지 않는 것이 관례입니다. 값에 공백이 포함된 경우 따옴표로 감싸면 됩니다.

🚨 API 키를 코드에 직접 쓰면 안 되는 이유

AI에게 “OpenAI API를 연동해줘”라고 요청하면, 가끔 코드 안에 API 키를 직접 넣는 예제를 만들어줍니다. 이렇게 하면 작동은 하지만 심각한 보안 위험이 생깁니다.

// ❌ 절대 하면 안 되는 코드
const openai = new OpenAI({
  apiKey: "sk-proj-abc123def456..."  // API 키가 코드에 직접 노출!
});

// ✅ 올바른 코드
const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY  // .env 파일에서 읽어옴
});

코드에 API 키를 직접 쓰면 이런 일이 벌어집니다.

• GitHub에 올리면 전 세계에 공개: Public 저장소라면 누구나 볼 수 있고, Private이라도 접근 권한이 있는 사람이 모두 볼 수 있습니다.
• 봇이 자동으로 스캔: GitHub에 올라간 API 키를 수 분 내에 탐지해서 악용하는 봇이 존재합니다. AWS 키가 노출되면 암호화폐 채굴에 악용되어 하루 수백만 원의 요금이 청구된 사례도 있습니다.
• 키를 바꿔야 할 때 코드 수정 필요: .env에 넣어두면 파일 하나만 바꾸면 되지만, 코드 곳곳에 직접 적어뒀으면 모든 파일을 찾아 수정해야 합니다.
• 환경별 설정 관리 불가: 개발할 때와 배포할 때 다른 키를 써야 하는데, 코드에 하드코딩하면 매번 수동으로 바꿔야 합니다.

🛠️ .env 파일 만들기 단계별 가이드

1️⃣ 프로젝트 루트에 파일 생성

프로젝트 폴더의 최상위(루트)에 .env.local 파일을 만듭니다. Next.js 프로젝트에서는 .env.local을 사용하는 것이 표준입니다.

# 터미널에서 프로젝트 폴더로 이동 후
# Windows PowerShell
New-Item -Name ".env.local" -ItemType File

# macOS / Linux
touch .env.local

또는 VS Code에서 프로젝트 폴더를 열고, 파일 탐색기에서 우클릭 → “New File” → .env.local을 입력해도 됩니다.

2️⃣ 환경변수 입력

생성한 파일을 열고 필요한 환경변수를 입력합니다.

# .env.local
# Supabase 설정
NEXT_PUBLIC_SUPABASE_URL=https://abcdefg.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6...

# 기타 API 키
OPENAI_API_KEY=sk-proj-...

3️⃣ 개발 서버 재시작

.env.local 파일을 수정한 뒤에는 개발 서버를 중지했다가 다시 시작해야 합니다. 환경변수는 서버 시작 시점에 한 번 읽히기 때문에, 파일만 저장하면 반영되지 않습니다.

# 개발 서버 중지: Ctrl+C
# 다시 시작
npm run dev
# 또는
pnpm dev

💻 코드에서 환경변수 사용하기

환경변수를 코드에서 사용하는 방법은 간단합니다. process.env.변수이름으로 참조하면 됩니다.

🔸 서버 측 코드 (Server Component, API Route)

// app/api/chat/route.ts
import { OpenAI } from "openai";

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

// process.env.OPENAI_API_KEY는 .env.local의 값을 읽어옵니다
// 브라우저에는 노출되지 않습니다

🔸 클라이언트 측 코드 (Client Component)

// components/supabase-provider.tsx
"use client";

import { createClient } from "@supabase/supabase-js";

// NEXT_PUBLIC_ 접두사가 있어야 클라이언트에서 접근 가능
const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
);

🛡️ .gitignore로 .env 파일 보호하기

.env 파일이 실수로 GitHub에 올라가지 않도록 .gitignore 파일에 반드시 추가해야 합니다. Next.js 프로젝트를 create-next-app으로 만들었다면 이미 포함되어 있지만, 직접 확인하는 것이 안전합니다.

# .gitignore 파일에 아래 내용이 있는지 확인
.env
.env.local
.env.development.local
.env.test.local
.env.production.local
.env*.local

확인하는 가장 빠른 방법은 터미널에서 확인하는 것입니다.

# .gitignore에 .env 관련 항목이 있는지 검색
# macOS / Linux
grep "env" .gitignore

# Windows PowerShell
Select-String -Path .gitignore -Pattern "env"

결과에 .env 관련 줄이 보이면 정상입니다. 아무것도 안 나오면 .gitignore 파일을 열어서 위의 내용을 직접 추가하세요.

📋 .env.example 파일 만들기

.env 파일은 Git에 올리지 않기 때문에, 다른 사람(또는 미래의 나)이 프로젝트를 받으면 어떤 환경변수가 필요한지 알 수 없습니다. 이 문제를 해결하는 것이 .env.example 파일입니다.

# .env.example — 이 파일은 Git에 올립니다
# 실제 값 대신 설명만 적습니다

# Supabase (https://supabase.com 에서 발급)
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=

# OpenAI (https://platform.openai.com 에서 발급)
OPENAI_API_KEY=

이렇게 변수 이름과 발급처만 적어두면, 프로젝트를 받은 사람이 “아, 여기서 키를 발급받아서 넣으면 되는구나”라고 바로 이해할 수 있습니다. .env.example은 비밀 값이 없으므로 Git에 올려도 안전합니다.

🌐 Vercel 배포 시 환경변수 설정

내 컴퓨터에서는 .env.local에서 값을 읽지만, Vercel에 배포하면 Vercel의 환경변수 설정에서 값을 읽습니다. .env.local 파일은 Git에 올라가지 않기 때문에, Vercel에 별도로 등록해야 합니다.

🖱️ Vercel 대시보드에서 설정

1. Vercel 대시보드에서 프로젝트를 선택합니다.
2. Settings → Environment Variables로 이동합니다.
3. Key에 변수 이름, Value에 실제 값을 입력합니다.
4. 환경(Production, Preview, Development)을 선택합니다. 보통 세 환경 모두 체크합니다.
5. “Save”를 클릭합니다.

💻 Vercel CLI로 설정

# Vercel CLI로 환경변수 추가
vercel env add OPENAI_API_KEY

# 현재 설정된 환경변수 목록 확인
vercel env ls

# Vercel의 환경변수를 로컬 .env.local로 가져오기
vercel env pull .env.local

vercel env pull 명령은 Vercel에 등록된 환경변수를 .env.local 파일로 자동으로 가져와줍니다. 팀원 간에 환경변수를 공유할 때 특히 편리합니다.

📋 환경변수 관리 점검 목록

🚨 실수 패턴과 예방법

💥 .env 파일을 만들었지만 .gitignore에 안 넣기

.env 파일을 만든 것만으로는 보호되지 않습니다. .gitignore에 추가하지 않으면 git add . 실행 시 함께 올라갑니다. 프로젝트를 만들자마자 가장 먼저 .gitignore를 확인하세요.

💥 NEXT_PUBLIC_ 접두사를 비밀 키에 사용하기

“환경변수가 안 읽힌다”는 이유로 모든 변수에 NEXT_PUBLIC_을 붙이는 경우가 있습니다. 이렇게 하면 비밀 키가 브라우저에 노출됩니다. 서버에서만 사용하는 키(SECRET, SERVICE_ROLE, PRIVATE 등)에는 접두사를 붙이지 마세요. 클라이언트에서 읽히지 않는 것이 정상입니다.

💥 .env 파일 수정 후 서버 재시작 안 하기

“값을 바꿨는데 안 바뀐다”는 질문의 90%는 서버 재시작을 안 했기 때문입니다. .env 파일은 서버 시작 시에만 읽히므로, 수정 후 반드시 개발 서버를 껐다가 다시 켜세요.

📂 .env 파일 종류 비교

Next.js는 여러 종류의 .env 파일을 지원합니다. 우선순위가 높은 파일이 낮은 파일의 값을 덮어씁니다.

비전공자가 바이브코딩을 하는 단계에서는 .env.local 하나만 사용해도 충분합니다. 프로젝트가 복잡해지면 환경별로 분리하면 됩니다.

💡 운영 팁

📌 AI에게 코드를 요청할 때 .env 사용을 명시하기

“Supabase 연동해줘”라고만 요청하면 AI가 코드에 키를 직접 넣는 경우가 있습니다. “Supabase 연동해줘. API 키는 환경변수(.env.local)에서 읽어오도록 만들어줘”라고 명시하면 처음부터 올바른 구조로 만들어줍니다.

📌 API 키 주기적으로 교체하기

보안 모범 사례는 API 키를 3~6개월마다 교체하는 것입니다. 키를 교체할 때는 .env.local의 값을 새 키로 바꾸고, Vercel 환경변수도 업데이트한 뒤, 서버를 재시작(또는 재배포)하면 됩니다.

📌 여러 프로젝트의 키를 한 곳에서 관리하기

프로젝트가 늘어나면 “어느 프로젝트에 어떤 키를 넣었는지” 헷갈릴 수 있습니다. 비밀번호 관리 앱(1Password, Bitwarden 등)에 프로젝트별 환경변수를 메모해두면 나중에 찾기 편합니다.

⚡ 면책조항

환경변수 관리는 처음에는 번거롭게 느껴지지만, 한 번 습관이 들면 자연스러워집니다. .env 파일 하나가 여러분의 API 키와 지갑을 지켜줍니다. 읽어주셔서 감사합니다.

❓ FAQ

질문을 누르면 답변이 펼쳐집니다.

🔗 관련 글

• AI가 만든 코드 검증하는 방법 — 보안 점검 가이드
• 바이브코딩 보안 체크리스트 — AI 코드 취약점 예방
• GitHub 가입부터 저장소 만들기까지
• 바이브코딩 시작 전 개발환경 세팅 완벽 가이드
• Node.js 설치부터 바이브코딩 시작까지 3단계

📑 참고 자료

• Next.js 공식 문서 — Environment Variables
• Vercel 공식 문서 — Environment Variables
• GitHub 공식 문서 — Secret Scanning

Brandon

IT 기획 10년차 / 비전공자를 위한 바이브코딩 블로그 운영 / vibe-start.com 제작

Building VibeStart — the fastest path for non-devs into AI coding. Launching on Product Hunt 2026-05-26.

vibe-start.com