.env 파일 파서

입력 예시

# 데이터베이스 설정
DB_HOST=localhost
DB_PORT=5432
DB_NAME=myapp
DB_PASSWORD="s3cr3t"
# API 키
API_KEY=
STRIPE_KEY=your-stripe-key
# 중복 키 예시
APP_ENV=development
APP_ENV=production

파서는 DB_PASSWORD의 따옴표를 제거하고, API_KEY에 “값이 비어 있습니다”, 두 번째 APP_ENV에 “중복된 키”를 표시하며, 상태 줄은 “유효 6개, 경고 2개.”입니다. 내보낸 env.json의 APP_ENV는 마지막 값입니다.

{
  "DB_HOST": "localhost",
  "DB_PORT": "5432",
  "DB_NAME": "myapp",
  "DB_PASSWORD": "s3cr3t",
  "API_KEY": "",
  "STRIPE_KEY": "your-stripe-key",
  "APP_ENV": "production"
}

콜론, 공백, 그 밖의 키 이름

dotenv는 YAML처럼 KEY: value도 읽지만 콜론 뒤에 공백이 있어야 합니다. dotenv가 건너뛰는 줄은 테이블에서 오류가 되고 내보내지지 않습니다. dotenv가 받는 드문 키는 경고가 붙고 내보내기에 포함됩니다.

SERVICE_NAME: 예약 서비스
export API_URL: https://api.example.kr/v1
DB HOST=db.internal
kakao.rest-key=your-rest-api-key
PORT:8080

{
  "SERVICE_NAME": "예약 서비스",
  "API_URL": "https://api.example.kr/v1",
  "kakao.rest-key": "your-rest-api-key"
}

상태 줄은 “유효 2개, 경고 1개, 오류 2개.”입니다. 3번째 줄은 키에 공백이 있어 dotenv의 키 패턴 [\w.-]+에 맞지 않으므로 오류이고, 5번째 줄은 콜론 뒤에 공백이 없습니다. Node.js 자체 파서(—env-file, util.parseEnv())는 규칙이 달라, Node.js 22.23.3은 이 텍스트에서 DB HOST와 kakao.rest-key를 읽고 콜론이 있는 세 줄은 모두 무시합니다.

proto라는 키만 내보내기 결과가 dotenv.parse()와 다릅니다. dotenv는 이 키를 버립니다.

__proto__=keep
A=1

{
  "__proto__": "keep",
  "A": "1"
}

감지되는 일반적인 .env 오류

• 등호 누락 — =도 콜론도 없어 키-값 쌍으로 파싱할 수 없는 줄.
• 콜론 표기 — PORT:8080, PORT : 8080은 dotenv가 건너뜁니다. PORT=8080 또는 PORT: 8080으로 쓰세요.
• 빈 값 — 키는 있지만 값이 비어 있음. 앱에 따라 런타임 오류가 발생할 수 있습니다.
• 중복 키 — 동일한 키가 두 번 이상 등장. dotenv는 마지막 값을 쓰지만 다른 로더도 그렇다는 보장은 없습니다.
• 일반적이지 않은 키 이름 — 키 이름은 영문자나 밑줄로 시작하고 영문자, 숫자, 밑줄만 쓰는 것이 안전합니다. ., -가 있거나 숫자로 시작하는 키도 dotenv는 읽습니다(경고). 공백 등이 있는 키는 읽지 않습니다(오류).
• 따옴표 없는 값 속 # — dotenv는 거기서부터 주석으로 보므로 COLOR=#fff는 빈 값이 되고 URL=https://example.com/#top은 #top이 사라집니다. 값을 따옴표로 감싸세요. 규칙은 dotenv 파싱 규칙 참고.

제한

• 변수를 펼치지 않습니다. ${HOME}/data는 그대로 남습니다. dotenv-expand, Docker Compose, 일부 프레임워크는 이런 참조를 펼칩니다.
• dotenv 규칙만 따릅니다. Node.js —env-file, Docker Compose의 env_file, Python의 python-dotenv, 셸의 source는 따옴표·콜론·export·#를 각자 다르게 처리합니다. 실제로 쓰는 로더로 확인하세요.
• 값은 평문으로 표시됩니다. 테이블은 시크릿을 가리지 않으므로 화면 공유에 주의하세요. 파일을 공유하기 전에 API 키 마스킹 도구로 값을 바꿀 수 있습니다.