Node.js process.env로 환경 변수 읽기

process.env는 셸이 Node.js 프로그램에 넘긴 환경 변수마다 속성이 하나씩 있는 객체입니다. process.env.PORT, process.env.DATABASE_URL처럼 읽습니다. 설정되지 않은 변수는 undefined이고, 설정된 변수는 항상 문자열입니다. 시작할 때 한 번 읽고, 기본값을 주고, 필요한 타입으로 바꾸세요.

// The shell normally sets these: PORT=8080 APP_NAME=shop node index.js
process.env.PORT = '8080';
process.env.APP_NAME = 'shop';

const port = Number(process.env.PORT ?? 3000);
const name = process.env.APP_NAME ?? 'my-app';
const region = process.env.REGION ?? 'eu-west';

console.log(name, 'on port', port, 'in', region);
console.log(typeof process.env.PORT, typeof port);

shop on port 8080 in eu-west가 출력되었습니다(REGION은 설정된 적이 없어서 기본값이 쓰였습니다). 이어서 string number가 나왔는데, 변수는 Number()로 바꾸기 전까지 텍스트입니다. 처음 두 대입을 지우고 다시 실행하면 모든 기본값을 볼 수 있습니다.

셸에서 환경 변수 설정하기

변수는 Node.js를 시작한 곳에서 옵니다. 터미널에서는 이렇게 합니다.

// macOS and Linux: for one command
PORT=8080 NODE_ENV=production node app.js

// macOS and Linux: for the rest of the terminal session
export PORT=8080

// Windows PowerShell
$env:PORT = "8080"; node app.js

// Windows cmd.exe
set PORT=8080
node app.js

호스팅 플랫폼(Heroku, Render, Vercel, Docker, Kubernetes)에는 같은 일을 하는 설정 화면이나 파일이 있고, 코드에서 읽는 방법은 같습니다.

모든 값은 문자열입니다

process.env 버그는 대부분 여기서 나옵니다. 'false'와 '0'은 비어 있지 않은 문자열이라서 truthy입니다.

// The shell normally sets this: DEBUG=false node index.js
process.env.DEBUG = 'false';

if (process.env.DEBUG) {
    console.log('naive check: debug is ON');
}

const debug = process.env.DEBUG === 'true';
console.log('correct check: debug is', debug ? 'ON' : 'OFF');

단순한 검사는 false로 설정한 변수에도 debug is ON을 출력했습니다. 그러니 기대하는 문자열과 정확히 비교하세요. 숫자라면 Number(process.env.X)가 값이 없을 때 NaN이 되므로, 첫 예제에서 ??로 한 것처럼 변환하기 전에 기본값을 적용하세요.

NODE_ENV

NODE_ENV는 Node.js 기능이 아니라 관례입니다. Node.js는 이 값을 설정하지 않고, 라이브러리가 읽습니다. 예를 들어 Express는 이 값이 production이면 에러 페이지에서 스택 트레이스를 숨기고, 많은 도구가 개발용 검사를 건너뜁니다.

// The shell normally sets this: NODE_ENV=production node index.js
process.env.NODE_ENV = 'production';

const isProduction = process.env.NODE_ENV === 'production';

console.log('mode:', process.env.NODE_ENV);
console.log('verbose logs:', !isProduction);

mode: production과 verbose logs: false가 출력되었습니다. 'production'을 'development'로 바꾸면 두 번째 줄이 뒤집힙니다. 라이브러리는 정확히 이 단어들을 확인하므로 production, development, test만 쓰세요.

.env 파일: --env-file과 dotenv

node 앞에 모든 변수를 매번 타이핑하는 건 금방 지칩니다. .env 파일을 쓰면 프로젝트 폴더에 한 줄에 하나씩 둘 수 있습니다.

// .env
PORT=8080
DATABASE_URL=postgres://localhost/shop
API_KEY=dev-key-123

Node.js 20.6 이후는 패키지 없이 플래그 하나로 읽습니다.

node --env-file=.env app.js

이전 버전이거나 이쪽이 더 편하다면 dotenv 패키지를 설치하고(npm install dotenv), 진입 파일 맨 위, process.env를 읽는 코드보다 앞에서 불러오세요.

require('dotenv').config(); // copies .env into process.env

console.log(process.env.PORT); // 8080

어느 쪽도 셸에서 이미 설정된 변수는 덮어쓰지 않으므로, 운영 환경의 설정이 파일보다 우선합니다.

빠진 변수는 일찍 실패시키기

데이터베이스 URL이 없다면 한 시간 뒤 첫 요청에서 죽을 것이 아니라, 시작할 때 분명한 메시지와 함께 멈춰야 합니다.

// The shell normally sets these
process.env.DATABASE_URL = 'postgres://localhost/shop';

const required = ['DATABASE_URL', 'API_KEY'];
const missing = required.filter((key) => !process.env[key]);

if (missing.length > 0) {
    console.log('Missing environment variables:', missing.join(', '));
} else {
    console.log('Config OK');
}

Missing environment variables: API_KEY가 출력되었습니다. 맨 위에 process.env.API_KEY = 'test';를 추가하면 Config OK가 출력됩니다. 실제 프로그램에서는 메시지 뒤에 process.exit(1)을 쓰세요. 배포 스크립트나 컨테이너 플랫폼은 0이 아닌 종료 코드를 보고 시작이 실패했다는 것을 압니다.

비밀 값은 절대 커밋하지 마세요

.env는 만든 날 바로 .gitignore에 넣으세요. 대신 변수 이름과 가짜 값을 적은 .env.example을 커밋해 두면 다른 사람도 무엇을 설정해야 할지 압니다. 한 번이라도 저장소에 푸시된 키는 나중에 커밋을 지우더라도 유출된 것으로 보고 교체해야 합니다.