.env 파일이 뭐야 — 비밀번호·API 키를 숨기는 곳

.env는 API 키나 비밀번호처럼 공개하면 안 되는 값을 코드와 분리해 따로 적어두는 파일입니다.
2026년 7월 기준으로, AI에게 코드를 받아 돌려보는 초보라면 이 파일을 거의 반드시 마주칩니다.
이 글을 읽으면 .env가 왜 필요한지, 어떻게 생겼는지, 왜 "절대 깃허브에 올리면 안 되는지"까지 한 번에 이해할 수 있습니다.

.env는 API 키·비밀번호 같은 "공개하면 안 되는 값"을 코드 바깥의 쪽지에 적어두는 파일입니다. 코드에서는 값을 직접 쓰지 않고 이 쪽지를 불러다 씁니다. 그리고 이 쪽지는 절대 깃허브에 함께 올리지 않습니다.

왜 .env가 필요한가

코드 안에 비밀번호나 API 키를 그대로 적어 넣는 건 생각보다 위험합니다.
가장 흔한 사고는 이렇습니다.
키를 코드에 적어둔 채 프로젝트를 깃허브 같은 공개 저장소에 올립니다.
그 순간 전 세계 누구나 그 키를 그대로 볼 수 있게 됩니다.
실제로 공개된 키를 자동으로 긁어가는 프로그램이 돌아다니고, 유출된 API 키로 요금이 청구되는 사고가 자주 일어납니다.
그래서 "비밀 값은 코드에 직접 쓰지 말고 따로 보관한다"는 규칙이 생겼습니다.
그 따로 보관하는 곳이 바로 .env 파일입니다.

.env 파일은 어떻게 생겼나

.env는 이름 그대로 점(.)으로 시작하는 아주 단순한 텍스트 파일입니다.
안에는 "이름=값" 형태의 줄이 나열돼 있을 뿐입니다.
비밀번호나 키를 적어두는 쪽지라고 생각하면 쉽습니다.

API_KEY=sk-1234abcd
DB_PASSWORD=my-secret-password
PORT=3000

왼쪽이 값을 부를 이름, 오른쪽이 실제 비밀 값입니다.
이름은 보통 대문자와 밑줄로 씁니다.
따옴표도, 복잡한 문법도 필요 없습니다.

아래 표처럼, 같은 비밀 값이라도 어디에 적느냐에 따라 안전함이 완전히 달라집니다.

키가 보이는 위치	코드 파일 안에 그대로 노출	코드 바깥 .env 파일에만 존재
깃허브에 올릴 때	키가 함께 공개됨	.env는 빼고 올릴 수 있음
키를 바꿀 때	코드 여기저기를 찾아 수정	.env 한 줄만 고치면 끝

코드에서는 어떻게 불러 쓰나

.env에 값을 적어뒀다면, 코드에서는 그 값을 직접 쓰지 않고 이름으로 불러옵니다.

자바스크립트(Node.js) 환경에서는 보통 process.env.이름 형태로 꺼냅니다.

const apiKey = process.env.API_KEY;

이렇게 하면 코드에는 진짜 키 대신 "API_KEY라는 쪽지를 꺼내 쓴다"는 표시만 남습니다.
실제 값은 .env 파일에만 있으니, 코드를 공유해도 비밀은 새지 않습니다.

AI가 준 코드에서 process.env가 보인다면, 바로 이 쪽지를 불러오는 부분입니다.

이 부분을 더 알고 싶다면 앞서 정리한 "API 키가 뭐야" 글을 함께 보면 이해가 빠릅니다.

---

.env는 절대 깃허브에 올리지 않는다

.env를 쓰는 이유의 절반은 "이 파일을 공유하지 않기 위해서"입니다.
비밀 값을 코드에서 분리해놓고 정작 .env를 통째로 깃허브에 올려버리면, 애써 나눈 의미가 사라집니다.
그래서 대부분의 프로젝트는 .env를 "올리지 말 것" 목록에 넣어둡니다.
그 목록이 바로 .gitignore라는 파일입니다.
.gitignore에 .env 한 줄을 적어두면, 깃이 이 파일을 아예 공유 대상에서 빼줍니다.

⚠️ .env를 만들었다면, 깃허브에 올리기 전에 .gitignore에 .env가 들어 있는지부터 확인하세요. 이 한 줄이 키 유출 사고의 대부분을 막아줍니다.

.gitignore가 정확히 무엇이고 어떻게 쓰는지는 다음 편에서 따로 다룹니다.

그런데 이게 AI랑 무슨 상관일까

요즘은 AI에게 코드를 받아 그대로 돌려보는 경우가 많습니다.

이때 AI가 준 코드에 process.env.API_KEY 같은 표현이 자주 등장합니다.

진짜 키는 네 .env에 넣고 코드에는 이름만 두라고, AI가 안내하는 셈입니다.
개인적으로는 이 방식이 초보에게도 좋은 습관을 강제해준다고 봅니다.
한 가지 주의할 점은, AI에게 "여기에 내 API 키를 넣어줘"라고 부탁하면 키가 코드에 그대로 박히기도 한다는 겁니다.
그래서 AI에게 코드를 받을 때는 "키는 .env에서 불러오게 해줘"라고 요청하는 편이 안전합니다.

정리

.env는 공개하면 안 되는 값을 코드와 분리해 담아두는 쪽지 같은 파일입니다.

코드에서는 process.env.이름으로 값을 불러 쓰고, 진짜 값은 .env에만 남깁니다.

그리고 이 파일은 .gitignore로 막아 절대 공개 저장소에 올리지 않습니다.
이 세 가지만 지켜도 초보가 가장 많이 겪는 키 유출 사고는 거의 피할 수 있습니다.

자주 묻는 질문

.env 파일은 직접 만들어야 하나요?

네, 보통 직접 만듭니다.

프로젝트 폴더 맨 위에 파일 이름을 정확히 .env로 지정해 새로 만들면 됩니다.

많은 프로젝트가 예시용으로 .env.example을 함께 두는데, 이건 값 없이 이름만 적힌 견본이라 공유해도 괜찮습니다.

.env를 실수로 깃허브에 올렸다면 어떻게 하나요?

가장 먼저 할 일은 유출된 키를 즉시 새 키로 바꾸는(재발급) 것입니다.
파일을 지우더라도 과거 기록에 키가 남아 있을 수 있어서, 파일 삭제보다 키 교체가 우선입니다.
그다음에 .gitignore에 .env를 추가해 같은 실수를 막으면 됩니다.
 
 

참고한 자료

환경변수와 process.env 사용법은 MDN과 Node.js 공식 문서 설명을 기준으로 정리했습니다. 실제 파일 이름·경로 규칙은 사용하는 도구·프레임워크에 따라 조금씩 다를 수 있어, 발행 전 각 공식 문서 확인이 필요합니다.