Node.js 환경변수 이해하고 사용하기

Node.js 환경변수 이해하고 사용하기

1. 환경변수(Environment Variables)란?

환경변수를 가장 쉽게 비유하자면, 컴퓨터에 붙이는 “설정 정보”입니다. 코드를 작성하다 보면, 코드 자체에는 포함하고 싶지 않지만, 프로그램이 동작하는 데 꼭 필요한 정보들이 있습니다. 예를 들면 아래와 같은 정보들입니다.

• API 키, 데이터베이스 비밀번호와 같은 민감한 정보 (보안)
• 개발 모드, 프로덕션(실서비스) 모드를 구분하는 정보 (설정)
• 서버 포트 번호, 데이터베이스 주소와 같이 배포 환경마다 달라지는 정보 (유연성)

이런 정보들을 코드에 직접 써넣는 대신, 라벨처럼 외부(운영체제나 실행 환경)에 설정해두고, 코드에서는 이 라벨의 이름만 불러다 쓰는 방식이 바로 환경변수입니다.

왜 사용해야 할까요?

1. 보안: 비밀번호 같은 민감 정보를 코드에서 분리하여 Git 같은 곳에 실수로 노출하는 것을 방지합니다.
2. 유연성: 코드를 수정하지 않고도 개발, 테스트, 실서비스 환경에 맞게 설정을 쉽게 변경할 수 있습니다.
3. 편의성: 여러 개발자가 각자 다른 설정(예: 로컬 DB)으로 작업할 수 있게 해줍니다.

---

2. Node.js 기본 환경변수 process.env

Node.js는 process라는 내장 객체를 통해 현재 실행 환경에 접근할 수 있는 통로를 제공합니다. 이 process 객체 안의 env 속성에는 모든 환경변수가 담겨있습니다.

윈도우나 Linux, Mac에 등록한 모든 환경 변수가 process.env 객체에 JSON 형태로 저장되어 있습니다.

아래는 process.env를 사용하는 가장 기본적인 예제입니다.

실습: /03-환경변수/01_process.js

// process.env 객체를 통해 모든 환경변수를 JSON 형태로 접근할 수 있다.
console.log("💻 모든 환경변수:", process.env);

// 특정 환경변수 값에 접근
// 운영체제마다 이름이 다르다. (Windows: Path, macOS/Linux: PATH)
// --> `||` (OR 연산자)를 사용하면 Path가 없을 경우 PATH로 대체하여 조회한다.
const path = process.env.Path || process.env.PATH;

console.log(path);

3. dotenv로 환경변수 관리하기

운영체제에 매번 환경변수를 설정하는 것은 매우 번거롭습니다. 관리할 변수가 많아지면 실수하기도 쉽다.

그래서 대부분의 Node 프로그램은 .env 파일에 환경변수를 기록해두고, dotenv라는 라이브러리를 사용해 파일의 내용을 process.env로 불러오는 방식을 가장 널리 사용합니다.

.env 파일이란?

프로젝트의 루트 디렉터리에 위치하는 이름=값 형식의 간단한 텍스트 파일입니다. 이 파일은 절대 Git에 올리면 안 됩니다!

dotenv 설치

먼저 프로젝트에 dotenv 라이브러리를 설치합니다.

$ yarn add dotenv
# 또는 npm install dotenv

.env 파일 생성

프로젝트 루트(03-환경변수 폴더)에 .env 라는 이름으로 새 파일을 만들고 아래 내용을 작성한다.

여기서 작성하는 내용은 임의로 작성하는 샘플 내용이므로 실제 프로젝트에는 프로젝트에 적합한 내용을 작성한다.

실습: /.env

# 환경변수 테스트용
MY_MESSAGE=Hello Node
IS_TEST=true

.env 파일 로드하기

실습: /03-환경변수/02_env.js

이제 .env 파일의 값들을 Node.js에서 어떻게 읽어오는지 코드로 확인해봅시다.

// 1. dotenv 모듈을 불러온다.
import dotenv from 'dotenv'; // ES Module 방식 (최신)

// 이 함수가 호출되는 순간 .env 파일의 내용이 process.env에 저장된다.
dotenv.config();

// 2. .env 파일에 저장된 값들을 process.env를 통해 사용한다.
console.log(`✅ 문자열 타입 환경변수: ${process.env.MY_MESSAGE}`);

// 3. Boolean 타입 환경변수 처리
// .env 파일의 모든 값은 문자열("true", "false")이므로, Boolean으로 변환해야 한다.
const isTest = process.env.IS_TEST === 'true';
console.log(`✅ Boolean 타입 환경변수: ${isTest}`);

4. 가장 중요한 규칙: .gitignore

.env 파일은 민감한 정보를 담고 있기 때문에 절대로 외부에 노출되어서는 안 됩니다.

특히, Git으로 코드를 관리할 때 .env 파일이 저장소(Repository)에 올라가지 않도록 반드시 .gitignore 파일에 등록해야 합니다.

프로젝트 루트에 .gitignore 파일을 만들고 아래 내용을 추가하세요.

.gitignore

# Node.js 기본 무시 파일
node_modules
npm-debug.log

# 환경변수 파일 (매우 중요)
.env

이렇게 하면 Git은 .env 파일을 추적하지 않으므로, 실수로 비밀번호를 세상에 공개하는 일을 막을 수 있습니다.