.env

.env는 로더가 읽어 프로그램에 환경 변수를 전달하는 텍스트 설정 파일입니다. 적용 문법과 순서는 읽는 도구에 따라 달라집니다. 실제 적용 여부는 로더 호출과 실행 설정에 달려 있습니다. 서버 주소나 실행 모드처럼 환경별 값을 코드와 분리할 때 쓰며, 파일에 적힌 값과 실행 중인 프로세스가 받은 값은 다를 수 있습니다.

파일과 실행 환경의 관계

Node.js 문서는 .env 파일을 변수 이름, 등호, 값으로 이루어진 항목을 담는 파일로 설명합니다. 예를 들어 서비스 주소를 한 변수에 적어 두면 프로그램은 코드 안의 고정 주소 대신 그 변수를 참조할 수 있습니다. 개발 환경과 운영 환경에서 코드가 같더라도 연결 대상은 다르게 지정하는 방식입니다.

환경 변수는 실행 중인 프로세스가 이용하는 값이고, .env는 그 값을 준비하는 파일입니다. 파일에 적힌 내용과 프로세스가 실제로 받은 값은 구별해야 합니다. 파일을 읽지 않았거나 다른 설정이 우선 적용됐다면 둘이 다를 수 있습니다. .env라는 이름도 널리 쓰이는 관례이며, 도구가 허용하면 다른 파일 이름을 지정할 수 있습니다.

파일 이름과 npm 패키지 이름인 dotenv도 같은 대상은 아닙니다. dotenv 공식 저장소의 패키지는 .env의 값을 읽어 Node.js의 process.env에 넣는 로더입니다. Node.js 자체에도 파일을 읽는 기능이 있으므로 .env를 쓴다고 반드시 이 패키지를 설치하는 것은 아닙니다. 어떤 기능이 로드를 담당하는지는 실행 방식에 달려 있습니다.

문법과 적용 순서

.env에는 여러 언어와 플랫폼이 공통으로 따르는 단일 정식 명세가 없습니다. Node.js의 문법 설명도 자체 규칙임을 밝힙니다. 다른 도구에서 사용하던 파일을 옮길 때는 따옴표, 줄바꿈, 주석을 처리하는 방식이 같은지 확인해야 합니다. 겉으로 비슷한 파일이라고 해서 모든 로더가 같은 값으로 해석하지는 않습니다.

Node.js가 읽은 값은 문자열입니다. 숫자나 참·거짓처럼 보이는 내용을 적어도 곧바로 숫자형이나 불리언형이 되지 않습니다. 포트 번호처럼 숫자로 계산해야 하는 값은 프로그램에서 변환하고 검사해야 합니다. 따옴표 안의 주석 기호는 값에 포함될 수 있으므로, 파일에 보이는 문자를 어디까지 값으로 읽는지도 문법에 따라 결정됩니다.

같은 변수 이름을 여러 곳에 지정하면 우선순위가 결과를 좌우합니다. 예를 들어 Vite의 환경 변수 규칙에서는 실행 전에 이미 존재하던 환경 변수가 .env 파일보다 우선하고, 모드 전용 파일의 값은 일반 파일의 값보다 우선합니다. 이는 Vite의 규칙이며 모든 로더에 그대로 적용되는 규칙은 아닙니다. 값을 고쳤는데 동작이 그대로라면 적용된 파일과 로드 시점도 함께 살펴야 합니다.

설정 분리와 비밀 보호의 범위

.env에 비밀번호나 API 키를 적는 경우가 있지만, 텍스트 파일에 옮겨 적는 행위 자체가 암호화는 아닙니다. dotenv 문서도 암호화를 별도 기능으로 설명합니다. 코드와 설정을 분리하면 환경별 값을 관리하기 쉬워지지만, 파일을 읽을 수 있는 사람이 그 값을 보지 못하도록 만드는 효과까지 생기지는 않습니다.

브라우저에서 실행할 코드로 전달되는 값은 특히 구분해야 합니다. Vite 문서는 VITE_ 접두사가 붙은 환경 변수가 클라이언트 코드에 노출된다고 설명하며, 여기에 비밀 API 키를 넣지 말라고 명시합니다. .env에 보관했다는 사실보다 최종적으로 어디에 포함되는지가 공개 여부를 결정합니다. 서버에서만 쓰려던 값도 빌드 과정에서 브라우저 코드에 들어가면 사용자에게 전달됩니다.

팀에서 공유하는 설정 항목과 개인이 보관하는 실제 값도 역할이 다릅니다. 필요한 변수 이름을 알리는 것과 비밀 값을 저장소에 올리는 것은 별개의 일입니다. Vite는 민감한 변수를 담을 수 있는 로컬 파일을 Git 추적에서 제외하도록 안내합니다. 설정 파일을 관리할 때는 로더가 무엇을 읽는지와 프로그램이 그 값을 어디에 사용하는지를 함께 확인해야 합니다.