환경변수와 .env란? 설정 방법과 API 키 보관 시 주의점

안녕하세요. 사랑받는 IT 프로덕트의 첫걸음, 똑똑한개발자입니다.

환경변수는 프로그램이 실행 환경에서 전달받는 설정값입니다. .env는 이런 값을 이름=값 형태로 적어두는 텍스트 파일로, 환경변수 자체와는 구분됩니다. 파일을 읽는 기능을 사용해 값을 실행 환경에 불러온 뒤 코드에서 참조합니다.

## 환경변수란 코드 밖에 맡겨두는 설정값입니다

환경변수는 프로그램이 실행될 때 바깥 환경에서 건네받는 값입니다. 코드는 설정값의 이름을 참조하고 실제 값은 실행 환경에서 제공합니다. .env는 일반 텍스트 파일이므로 자체적으로 암호화된 금고는 아닙니다.

코드를 고치지 않고 노트북에서는 테스트 키를, 서버에서는 운영 키를 쓸 수 있는 것도 이 덕분입니다. API 키, 데이터베이스 주소, 결제 비밀 키가 대표적입니다.

환경변수 .env 파일은 이렇게 쓰고 읽습니다

.env는 프로젝트 맨 위 폴더에 두는 텍스트 파일입니다. 한 줄에 하나씩 이름=값으로 적고, # 뒤에 쓴 내용은 주석으로 처리됩니다.

Node.js는 패키지 없이도 .env를 읽습니다.

Node.js 공식 문서 기준으로 --env-file 옵션은 v20.6.0에 들어왔고, v24.10.0과 v22.21.0부터 정식 기능이 됐습니다. node --env-file=.env index.js로 실행하면 코드에서 process.env.API_KEY로 값을 꺼내 쓰면 됩니다. 이보다 낮은 버전이라면 dotenv 패키지를 설치하고 require('dotenv').config()를 첫 줄에 넣으면 됩니다.

Python은 python-dotenv로 불러옵니다.

pip install python-dotenv 후 load_dotenv()를 호출하면 값이 os.environ에 들어가고, os.getenv('API_KEY')로 읽습니다.

.env는 .gitignore에 넣고 .env.example만 공유합니다

.env 파일은 저장소에 올리지 않습니다.

dotenv 공식 안내는 ".env를 커밋해야 하나"라는 질문에 암호화하지 않았다면 아니라고 답합니다. .gitignore에 .env를 적으면 아직 추적하지 않는 파일을 제외할 수 있습니다. 이미 추적하거나 커밋한 파일에는 별도 조치가 필요합니다.

대신 값을 비운 .env.example을 남깁니다.

새 팀원을 위해 API_KEY=처럼 이름만 남긴 .env.example을 저장소에 함께 올려둡니다. 받은 사람은 이 파일을 복사해 자기 키만 채우면 됩니다.

배포 서버와 프론트엔드는 환경변수 넣는 곳이 다릅니다

.env는 내 노트북에만 있으니 배포 서버는 그 값을 모릅니다.

Vercel은 값을 넣은 뒤 다시 배포해야 반영됩니다.

Vercel 공식 문서 기준으로 프로젝트의 Environment Variables 메뉴에서 이름과 값을 넣고 Production·Preview·Development 중 적용 환경을 고릅니다. 기존 배포에는 반영되지 않으니 저장 후 한 번 더 배포해야 합니다.

공개 접두어가 붙은 변수는 누구나 볼 수 있습니다.

Next.js 문서에 따르면 NEXT_PUBLIC_ 변수는 빌드 때 브라우저용 자바스크립트에 값이 그대로 박힙니다. 개발자 도구만 열어도 보입니다. 비밀 키는 서버 쪽 API를 거쳐 호출해야 합니다.

키가 유출됐다면 지우기보다 폐기가 먼저입니다

키를 깃허브에 올렸다면 파일만 지워서는 해결되지 않습니다. 커밋 기록에 값이 그대로 남아 있거든요. 먼저 발급처 콘솔에서 그 키를 즉시 폐기하고, 새로 발급받은 키로 .env와 배포 대시보드를 함께 바꿉니다. 깃허브의 push protection이 공개 저장소로 가는 비밀 값 푸시를 기본으로 막아주지만, 그것만 믿긴 어렵습니다.

세부 설정과 지원 범위는 Node.js 환경변수 안내를 참고해 보세요.

설정과 운영까지 이어지는 개발

개발할 때 잘 되던 기능이 배포 후에는 다르게 동작하기도 합니다. 코드와 함께 설정값이 어디에서 관리되는지 살펴보면 상황을 이해하기 쉬워집니다.

똑똑한개발자는 UX/UI 디자인과 웹·앱 개발을 함께 진행합니다. 필요한 화면과 기능을 정리하고, 실제 이용과 운영을 고려해 서비스를 만들어가는 과정을 돕습니다.

지금 만들고 있는 서비스나 개선하고 싶은 부분이 있다면 아래 똑똑한개발자 링크로 편하게 이야기 남겨주세요. 함께 살펴보겠습니다. 감사합니다. :)