환경 변수와 .env (Environment Variables)
환경 변수는 프로그램이 실행 환경에서 읽는 설정값입니다. .env는 이 값을 적어 두는 파일 형식 중 하나이며 파일 자체가 값을 암호화하거나 유출을 막지는 않습니다.
같은 말:환경변수Environment Variablesdotenv.env 파일
🤔 .env 파일에 적으라는 안내를 받았을 때
AI에게 API 연동을 부탁하면 .env 파일에 키를 넣으라는 말을 들을 수 있습니다. API 키는 서비스에 요청할 때 사용하는 자격 정보입니다. 모든 설정값이 비밀은 아니지만 비밀 키가 공개되면 다른 사람이 여러분의 권한이나 사용량을 이용할 수 있습니다.
🔑 환경 변수와 파일은 다릅니다
환경 변수(Environment Variable)는 프로그램이 실행 환경에서 읽는 이름과 값의 쌍입니다. 비밀번호뿐 아니라 언어, 실행 모드, 공개 사이트 주소도 설정할 수 있습니다.
.env는 이런 값을 적어 두는 일반 텍스트 파일입니다. 파일을 만들기만 하면 모든 프로그램이 자동으로 읽는 것은 아닙니다. 사용하는 도구의 로딩 규칙을 확인해야 합니다. 예를 들어 웹 앱 개발 도구인 Next.js는 프로젝트 루트의 .env 계열 파일을 읽는 기능이 있습니다. 루트는 package.json 같은 프로젝트 설정 파일이 있는 최상위 폴더입니다.
🔐 사물함 비밀번호를 따로 보관하는 이유
사물함 문에 비밀번호를 붙이는 대신 지갑에 보관하는 상황을 떠올려 봅니다. 코드와 설정을 나누면 코드를 공유할 때 비밀을 함께 보내는 일을 줄일 수 있습니다. 다만 지갑을 통째로 건네면 비밀번호가 보이듯 .env 파일을 보내거나 화면에 출력하면 값은 노출됩니다. 파일 이름이 보안을 보장하는 것은 아닙니다.
# 구조를 읽기 위한 가상 예시이며 실제 키가 아닙니다
API_KEY=practice-only-not-a-key
NEXT_PUBLIC_SITE_NAME=모임 메모등호 왼쪽은 이름, 오른쪽은 값입니다. 서버 코드에서 process.env.API_KEY로 읽는 방식은 Node.js 계열 예시입니다. 다른 언어와 도구에는 다른 방법이 있습니다. 값을 읽었다고 로그나 응답에 그대로 출력하지 않습니다.
⚠️ .gitignore가 막는 것과 못 막는 것
.gitignore는 아직 Git이 추적하지 않는 파일을 기록 대상에서 제외하는 규칙입니다. Git은 파일 변경을 기록하는 도구입니다. 실제 사용하는 .env와 .env.local 등 비밀 파일 이름이 규칙에 포함되는지 봅니다. 다음은 한 가지 예입니다.
.env
.env.*
!.env.example마지막 줄은 변수 이름과 가상 값만 담은 .env.example을 공유하려고 예외로 둔 것입니다. 그 파일에 실제 비밀을 적으면 안 됩니다. 기존 프로젝트의 규칙을 통째로 덮어쓰지 않고 필요한 범위를 확인합니다.
이미 Git에 기록한 파일에는 나중에 추가한 ignore 규칙만으로 추적이 멈추지 않습니다. git status에 없다는 사실도 충분하지 않습니다. 추적 중이지만 변경이 없는 파일은 나오지 않기 때문입니다. Git을 사용할 수 있다면 해당 프로젝트 폴더의 터미널에서 git ls-files -- .env .env.local은 이 두 이름이 추적 중인지 보여 줍니다. 이름이 나오면 추적 중이며 아무것도 나오지 않으면 이 두 경로는 추적되지 않는 상태입니다. 이것만으로 이전 유출 여부나 다른 파일의 비밀 포함 여부를 판단하지는 않습니다. 다른 이름의 비밀 파일도 실제 이름으로 확인해야 합니다.
비밀이 원격 저장소나 공유 로그에 노출됐다면 파일만 지워 끝내지 않습니다. 해당 키를 폐기하고 필요한 새 키를 발급받아 사용처를 바꿉니다. 기록 정리와 사용 내역 확인도 필요하며 이미 전달된 비밀이 회수됐다고 가정하지 않습니다.
🌐 공개 접두사와 배포 환경
Next.js에서 NEXT_PUBLIC_ 접두사는 브라우저에 전달할 설정에 사용합니다. 해당 값은 빌드할 때 브라우저 코드에 포함될 수 있으므로 서버용 비밀 키에 붙이지 않습니다. 다른 프레임워크는 접두사와 규칙이 다릅니다. 접두사가 없는 값도 서버가 응답에 실어 보내면 노출될 수 있습니다.
내 컴퓨터의 .env가 배포 서버에 자동 전달된다고 가정하지 않습니다. 배포 플랫폼에서 개발, 미리보기, 운영 중 어느 환경에 값을 등록하는지 확인합니다. 운영 데이터베이스 연결값을 시험 환경에 잘못 넣으면 연습 중 실제 데이터가 바뀔 수 있습니다.
값을 바꿨는데 그대로라면 파일 위치와 변수 이름, 우선 적용되는 다른 설정 및 재시작이나 재배포 필요 여부를 확인합니다. Next.js의 공개 변수처럼 빌드 시점에 포함된 값은 환경 설정만 바꿔도 이미 만든 코드에 곧바로 반영되지 않습니다.
개발 환경과 운영 환경은 설정을 따로 확인합니다. 비밀 값은 공개 코드와 이미지 및 응답에 넣지 않습니다.
💼 다른 컴퓨터에서 실행이 안 될 때
새 컴퓨터에 코드를 내려받았는데 필요한 설정이 빠져 있을 수 있습니다. 프로젝트 안내와 .env.example의 변수 이름을 먼저 확인합니다. 비밀 값을 AI 대화에 그대로 붙여 넣는 대신 필요한 이름, 값을 찾지 못했다는 오류, 실행 환경만 전달합니다. 오류에 비밀이 포함됐다면 가립니다.
배포 뒤에만 실패하면 해당 환경의 이름과 설정을 대조하고 로그로 원인을 좁힙니다. 환경 변수 누락이 모든 오류의 원인은 아닙니다.
📝 가상 설정 두 개 구분하기
메모장에 아래 세 줄을 적습니다. 실제 키 발급이나 프로젝트 수정은 필요하지 않습니다.
API_KEY=practice-only-not-a-key
NEXT_PUBLIC_SITE_NAME=모임 메모
실행 대상=Next.js 미리보기 환경사이트 이름은 방문자에게 보여도 되지만 API_KEY 자리에 실제 서버용 비밀을 넣는다면 공개하면 안 됩니다. AI에게 “변수 이름과 용도를 구분하고 비밀 값은 출력하지 않는 점검표를 만들어 줘”라고 요청해 볼 수 있습니다.
답변에서 API_KEY에 NEXT_PUBLIC_을 붙이라고 하거나 .env에 넣었으니 안전하다고 끝내면 본문 기준으로 수정합니다. 이번에는 미리보기 환경에 API_KEY가 빠졌다고 바꿔 봅니다. 운영 값을 무조건 복사하는 대신 시험용 서비스에 맞는 값을 해당 환경에 등록해야 한다고 설명할 수 있으면 연습을 마친 것입니다.
📋 3줄 요약
-
환경 변수는 실행 환경에서 읽는 설정값이고 .env 파일 자체가 값을 암호화하거나 유출을 막지는 않습니다.
-
비밀 파일의 Git 추적 여부와 공개 접두사 및 응답 노출을 각각 확인합니다.
-
배포 환경별 값을 구분하고 비밀이 노출됐다면 키 폐기와 사용처 갱신을 진행합니다.
📚 참고 자료
공식 문서 확인: 2026년 10월 3일.

제대로 이해했는지 한 문제로 확인해 볼까요?
답을 고르면 바로 풀이가 나와요.
비밀 키가 있는 .env를 아직 Git에 기록하지 않았습니다. 실수로 커밋하지 않도록 먼저 할 일은 무엇인가요?
예제나 확인 질문을 직접 시도한 뒤 완료 표시해요. 더 연습할 내용이 남으면 표시하지 않고 다음 글을 읽어도 됩니다. 완료 버튼은 이해도를 채점하지 않으며 잘못 표시하면 취소할 수 있어요.

