.env 파일에서 헷갈리는 것들, 직접 실행해서 확인한 답 7가지

.env 파일이 헷갈리는 근본적인 이유는 하나입니다. .env에는 공식 표준이 없습니다. 어떤 파서(Node.js 내장 --env-file, dotenv, docker compose, 각종 프레임워크)가 읽느냐에 따라 같은 파일이 다르게 해석될 수 있고, 실제로 이 글을 쓰면서 그런 사례를 하나 확인했습니다.

그래서 이 글은 문서를 요약하는 대신, 헷갈리는 상황을 하나씩 실제로 실행해서 답을 확인했습니다. 검증 환경은 Node.js v22.14.0의 내장 --env-file 옵션이고, 파서 간 차이가 있는 항목은 dotenv 17.4.2로 같은 파일을 다시 읽어 비교했습니다.

다루는 질문:

1. 값에 공백이 있으면 따옴표를 써야 하나?
2. 값 안에 #이 있으면 어떻게 되나?
3. 같은 키를 두 번 쓰면 어느 값이 이기나?
4. KEY = value처럼 = 양옆에 공백을 둬도 되나?
5. export KEY=value 형식도 읽히나?
6. "\n"을 쓰면 진짜 줄바꿈이 되나?
7. .env를 git에 올려도 되나?

1. 값에 공백이 있으면 따옴표를 써야 하나?

따옴표 없이도 읽히긴 합니다.

GREETING=hello world      → "hello world"
GREETING="hello world"    → "hello world"

둘 다 같은 결과입니다. 다만 값 뒤에 실수로 붙은 공백은 따옴표가 없으면 잘려 나갑니다.

KEY=value␣␣␣              → "value"   (뒤 공백 제거됨)

보통은 잘리는 쪽이 원하는 동작이지만, 공백이 값의 일부여야 하는 경우라면 따옴표가 필수입니다. 어느 쪽이든 의도를 명확히 하려면 공백이 들어가는 값은 따옴표로 감싸는 습관이 안전합니다.

2. 값 안에 #이 있으면 어떻게 되나?

이 질문이 이 글에서 가장 중요합니다. 파서마다 답이 다르기 때문입니다. 같은 한 줄을 두 파서로 읽은 결과입니다.

PASSWORD=abc#def

node --env-file  → "abc#def"
dotenv 17.4.2    → "abc"

Node.js 내장 파서는 # 이후까지 값으로 살리지만, dotenv는 따옴표 없는 #부터를 인라인 주석으로 보고 잘라냅니다. 비밀번호나 토큰에 #이 들어 있으면, dotenv를 쓰는 환경에서만 뒷부분이 조용히 잘린 채 동작한다는 뜻입니다. 에러도 나지 않아서 “비밀번호가 맞는데 인증이 실패하는” 형태로 나타납니다.

따옴표로 감싸면 두 파서 모두 전체 값을 살립니다.

PASSWORD="abc#def"

node --env-file  → "abc#def"
dotenv 17.4.2    → "abc#def"

#이 들어갈 수 있는 값(비밀번호, 해시, URL fragment)은 무조건 따옴표로 감싸는 것이 파서 차이를 피하는 유일한 방법입니다.

3. 같은 키를 두 번 쓰면 어느 값이 이기나?

KEY=first
KEY=second

node --env-file  → second
dotenv 17.4.2    → second

두 파서 모두 나중에 나온 값이 이깁니다. 문제는 이게 에러 없이 조용히 일어난다는 점입니다. 수백 줄짜리 .env에서 같은 키가 위아래에 흩어져 있으면, 위쪽 값을 아무리 고쳐도 반영이 안 되는 미스터리를 겪게 됩니다. 파일이 길어졌다면 중복 키부터 의심해 볼 만합니다.

4. = 양옆에 공백을 둬도 되나?

KEY = value               → "value"

Node.js 내장 파서와 dotenv 모두 공백을 정리하고 읽어줍니다. 다만 셸에서 source로 같은 파일을 읽을 때는 KEY = value가 문법 오류이므로, 파일을 셸과 겸용할 가능성이 있다면 붙여 쓰는 관례를 따르는 편이 좋습니다.

5. export KEY=value 형식도 읽히나?

export KEY=value          → "value"

읽힙니다. export 접두사는 셸에서 source .env로 읽는 것을 겸하려는 관례인데, Node.js 내장 파서는 이를 인식하고 무시해 줍니다. 다만 이것도 표준이 아니라 파서의 배려이므로, 모든 도구가 지원한다고 가정하지 않는 것이 안전합니다.

6. “\n”을 쓰면 진짜 줄바꿈이 되나?

MSG="line1\nline2"        → "line1
                             line2"

Node.js 내장 파서 기준으로, 큰따옴표 안의 \n은 실제 줄바꿈 문자로 변환됩니다. 여러 줄짜리 인증서나 private key를 한 줄로 넣을 때 쓰는 방식입니다. 이 동작 역시 파서마다 지원 범위가 다르므로(작은따옴표에서는 안 되는 파서도 있습니다), 여러 줄 값을 쓴다면 실제 사용할 파서로 한 번 확인해 보는 것을 권합니다.

7. .env를 git에 올려도 되나?

여기는 실행해 볼 것도 없이 답이 정해져 있습니다. 올리면 안 됩니다. .env에는 API key와 비밀번호가 들어가고, git에 커밋된 값은 저장소를 볼 수 있는 모든 사람과 모든 clone에 영구히 남습니다.

관례는 이렇습니다.

• .env — 실제 값. .gitignore에 등록하고 절대 커밋하지 않습니다.
• .env.example — 키 이름만 있고 값은 비운 템플릿. 이것만 커밋해서 “어떤 변수가 필요한지”를 공유합니다.

이미 커밋한 적이 있다면, 히스토리에서 파일을 지우는 것으로는 부족합니다. 한 번이라도 push된 비밀 값은 유출된 것으로 간주하고 **키 자체를 재발급(rotate)**하는 것이 원칙입니다.

두 .env가 어긋났는지 확인해야 할 때

개발용과 운영용, 또는 내 로컬과 팀 템플릿(.env.example)이 어긋나서 생기는 문제 — 한쪽에만 있는 키, 값이 달라진 키, 위 3번 같은 중복 키 — 는 Stellar Brief의 .env Diff로 확인할 수 있습니다. 두 설정을 붙여넣으면 누락된 키와 달라진 항목을 비교해 주고, 중복 키도 경고합니다. 기본 화면에는 실제 값을 표시하지 않으며, 입력한 내용은 브라우저에서만 처리되고 서버로 전송되지 않습니다. 그래도 실제 운영 비밀 값보다는 값을 지운 사본으로 비교하는 것을 권합니다.

표준이 없는 파일 형식을 다루는 요령은 결국 하나입니다. 문서나 습관을 믿지 말고, 실제 사용하는 파서에서 어떻게 읽히는지 확인할 것 — 이 글이 그 확인을 조금 줄여줬기를 바랍니다.