Node.js 교재 · 17편 · 환경변수

환경변수와 dotenv — .env로 비밀 분리

DB 비밀번호를 코드에 박지 말 것. .env 한 줄이 평생 사고 방지.

실수 1위 — DB 비밀번호·API 키를 코드에 박아 GitHub 에 올리는 것. 공개 저장소면 1분 내 봇이 스캔해 가져간다. 비공개라도 팀원·외부 계약자가 모두 보게 됨.

해답은 단순 — 설정값을 코드와 분리. 환경변수가 표준 도구. .env 파일로 로컬 관리, production 은 호스팅 환경 변수로. Node 22 부터는 dotenv 패키지도 필요 없이 내장으로 가능.

1. process.env — Node 의 기본 창구

Node 가 자동으로 제공하는 객체. OS 환경변수와 부모 프로세스에서 받은 값이 다 들어 있다.

// server.js
console.log(process.env.HOME);    // '/home/user'
console.log(process.env.PATH);    // '/usr/bin:/bin:...'
console.log(process.env.PORT);    // undefined (설정 안 했으면)

const port = Number(process.env.PORT ?? 3000);
app.listen(port);

주의 — 모든 값이 문자열. 숫자가 필요하면 Number(), 불리언이면 === 'true' 비교. 환경변수가 없으면 undefined. ?? 또는 || 로 기본값.

2. .env 파일 — 로컬 비밀 분리

프로젝트 루트에 .env 파일:

# .env
DATABASE_URL=postgres://user:pass@localhost:5432/mydb
JWT_SECRET=super-long-random-string-at-least-32-chars
API_KEY_OPENAI=sk-abc123...
NODE_ENV=development
PORT=3000

규약 — KEY=value, 한 줄 한 변수, 따옴표 보통 안 씀. 같은 줄 주석은 #.

.gitignore 에 무조건 추가 — .env 는 절대 git 에 커밋 금지. .gitignore 첫 줄에 .env* 박아두기. 대신 .env.example (값 빈 키 목록)은 커밋해서 팀원이 어떤 변수가 필요한지 알게.

3. Node 22 내장 dotenv — 패키지 없이

옛날엔 dotenv npm 패키지가 표준이었는데 Node 20.6 부터 내장. 22 에선 정식 stable.

$ node --env-file=.env server.js

이 한 줄로 .env 의 모든 값이 process.env 에 자동 주입. 패키지 import 도 코드 변경도 필요 없다. package.json scripts 에 박아두면 더 편함.

// package.json
{
  "scripts": {
    "dev":   "node --env-file=.env --watch server.js",
    "start": "node --env-file=.env server.js"
  }
}

여러 파일도 가능 — --env-file=.env --env-file=.env.local. 뒤 파일이 덮어쓴다. 옛 dotenv 패키지의 NODE_ENV 자동 매핑이 필요하면 아직 그걸 써도 됨.

4. NODE_ENV — 환경 분기의 표준 키

Node 생태계의 약속된 변수. development · production · test 세 값이 표준.

if (process.env.NODE_ENV === 'production') {
  // 에러 스택 숨김·로그 최소화·캐시 적극 사용
  app.use(compression());
} else if (process.env.NODE_ENV === 'test') {
  // 테스트 DB 사용
  db = new TestDatabase();
} else {
  // 개발: 자세한 로그·hot reload
  app.use(morgan('dev'));
}

많은 라이브러리(Express·React·Vue)가 자동으로 NODE_ENV 를 확인해 production 최적화를 켠다. 배포 환경에선 무조건 NODE_ENV=production 설정 — 안 하면 라이브러리들이 dev 모드로 돌아 느림.

5. 검증 — Zod 로 시작할 때 한 번

가장 큰 사고 — 필수 환경변수 누락인데 모르고 서버 시작. 첫 요청에서야 undefined.length 같은 에러로 깨짐. 새벽 사고.

대비 — 서버 시작 시점에 모든 환경변수를 한 번에 검증.

// env.js
import { z } from 'zod';

const Env = z.object({
  NODE_ENV: z.enum(['development', 'production', 'test']),
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  PORT: z.string().regex(/^\\d+$/).transform(Number).default('3000'),
  API_KEY_OPENAI: z.string().startsWith('sk-'),
});

const parsed = Env.safeParse(process.env);
if (!parsed.success) {
  console.error('❌ 환경변수 오류:');
  console.error(parsed.error.flatten().fieldErrors);
  process.exit(1);
}

export const env = parsed.data;   // 타입 추론까지 자동
console.log('✅ 환경변수 OK');

이제 코드에서 process.env.PORT 대신 env.PORT — 타입 안전 + 누락 검출. 서버는 잘못된 설정으로 절대 시작하지 않는다.

왜 검증이 중요한가 — 환경변수 오타·누락은 production 에서 가장 자주 일어나는 사고. 새 서버 배포 시 환경변수 한 줄 빼먹어 일요일 새벽 호출 받기 싫으면, Zod 검증 12줄이 가장 싼 보험. 회사 코드라면 무조건.

요약 — 17편 좌표

여기까지 정리. process.env 는 모든 값이 문자열 → 변환 필요. 로컬 비밀은 .env 파일 + .gitignore 필수, 팀 공유는 .env.example. Node 22 부터 --env-file=.env 한 줄로 패키지 없이 동작. NODE_ENV 는 표준 분기 키 — production 에선 반드시 설정. 서버 시작 시 Zod 로 검증 한 번이면 누락 사고 방지. 다음 편에서 진짜 DB 연동 — node-postgres.

다음 편 예고 — PostgreSQL 연동

node-postgres(pg) 로 CRUD. 18편.