Skip to content
VibeStartVibeStart介绍博客
← 返回列表

.env 파일이란? API 키 안전하게 관리하는 방법 (2026)

.env 파일의 개념부터 API 키를 안전하게 관리하는 방법까지 비전공자도 따라 할 수 있는 실전 가이드입니다. Next.js 환경변수 설정, .gitignore 보호, Vercel 배포 시 환경변수 등록까지 정리합니다.

env 파일 사용법API 키 관리환경변수 설정NEXT_PUBLIC 환경변수.gitignore 설정Vercel 환경변수바이브코딩 보안Next.js 환경변수env.local 사용법API 키 보안

📄 .env 파일이란 무엇인가

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

쉽게 비유하면, 코드가 "설계도"라면 .env 파일은 "금고"입니다. 설계도(코드)는 누구에게나 보여줄 수 있지만, 금고(.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 저장소라면 누구나 볼 수 있습니다.
  • 봇이 자동으로 스캔: GitHub에 올라간 API 키를 수 분 내에 탐지해서 악용하는 봇이 존재합니다.
  • 키를 바꿔야 할 때 코드 수정 필요: .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-...

NEXT_PUBLIC_ 접두사의 의미: Next.js에서 NEXT_PUBLIC_으로 시작하는 환경변수는 브라우저(클라이언트)에서도 접근할 수 있습니다. 이 접두사가 없는 변수는 서버에서만 사용 가능합니다. API 비밀 키에는 절대 NEXT_PUBLIC_을 붙이지 마세요.

3. 개발 서버 재시작

.env.local 파일을 수정한 뒤에는 개발 서버를 중지했다가 다시 시작해야 합니다. 환경변수는 서버 시작 시점에 한 번 읽히기 때문입니다.

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

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

서버 측 코드 (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!
);

⚠️ NEXT_PUBLIC_ 변수는 브라우저에 노출됩니다. NEXT_PUBLIC_으로 시작하는 변수는 빌드 시점에 코드에 직접 삽입됩니다. Supabase의 anon 키처럼 공개해도 괜찮은 값만 이 접두사를 사용하세요.

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

.env 파일이 실수로 GitHub에 올라가지 않도록 .gitignore 파일에 반드시 추가해야 합니다.

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

📋 .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=

🌐 Vercel 배포 시 환경변수 설정

내 컴퓨터에서는 .env.local에서 값을 읽지만, Vercel에 배포하면 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

📂 .env 파일 종류 비교

파일용도Git에 올리기우선순위
.env.local내 컴퓨터 전용 비밀 값❌ 절대 안 됨가장 높음
.env.development.local개발 환경 전용❌높음
.env.development개발 환경 공유 값⚠️ 비밀 없으면 가능보통
.env모든 환경 기본값⚠️ 비밀 없으면 가능가장 낮음
.env.example가이드 문서✅ 반드시 올림—

비전공자가 바이브코딩을 하는 단계에서는 .env.local 하나만 사용해도 충분합니다.

🚨 실수 패턴과 예방법

  • .env 파일을 만들었지만 .gitignore에 안 넣기: .gitignore에 추가하지 않으면 git add . 실행 시 함께 올라갑니다.
  • NEXT_PUBLIC_ 접두사를 비밀 키에 사용하기: 모든 변수에 NEXT_PUBLIC_을 붙이면 비밀 키가 브라우저에 노출됩니다.
  • .env 파일 수정 후 서버 재시작 안 하기: .env 파일은 서버 시작 시에만 읽히므로, 수정 후 반드시 서버를 재시작하세요.

💡 운영 팁

  • AI에게 코드를 요청할 때 .env 사용을 명시하기: "API 키는 환경변수(.env.local)에서 읽어오도록 만들어줘"라고 명시하세요.
  • API 키 주기적으로 교체하기: 보안 모범 사례는 API 키를 3~6개월마다 교체하는 것입니다.
  • 여러 프로젝트의 키를 한 곳에서 관리하기: 비밀번호 관리 앱(1Password, Bitwarden 등)에 프로젝트별 환경변수를 메모해두면 편합니다.

🔗 관련 글

← 返回列表