개발 환경 설정이 먹지 않을 때

.env 파일에 분명 설정을 적었는데 앱에서 인식하지 못한다. 또는 포트 3000을 쓰기로 했는데 포트 8080에서 시작한다.

환경 변수 읽는지 확인하기

먼저 앱이 정말로 환경 변수를 읽는지 확인한다.

# .env 파일 확인
cat .env

# 현재 환경 변수 확인
echo $PORT
echo $NODE_ENV

# 명시적으로 환경 변수 설정 후 실행
PORT=3001 npm start

// 앱이 환경 변수를 제대로 읽는가
console.log('PORT:', process.env.PORT);
console.log('NODE_ENV:', process.env.NODE_ENV);

시작 로그에서 "Server running on port 3000"이 나온다면, process.env.PORT를 사용하고 있다. 콘솔에 아무것도 안 나온다면 앱이 읽고 있지 않은 것이다.

.env 파일 위치 확인

.env 파일이 프로젝트 루트에 있는가?

# 프로젝트 루트에서
ls -la .env

# 없으면 만든다
echo "PORT=3000" > .env

많은 앱은 .env 파일을 자동으로 로드한다 (dotenv 라이브러리 사용). 하지만:

• 빌드 시점에 환경 변수를 구워 넣으면, .env 파일 변경이 반영되지 않음
• 번들 도구 (Webpack, Vite 등)가 다르면 로드 방식이 다름

// 직접 dotenv 로드
require('dotenv').config();

console.log('PORT:', process.env.PORT);

빌드 시점 vs 런타임

Next.js 같은 프레임워크는 빌드 시점에 환경 변수를 결정한다.

# .env.local 파일 만들기 (Next.js)
echo "NEXT_PUBLIC_API_URL=http://localhost:3000" > .env.local

# 빌드
npm run build

# 실행
npm start

빌드 후에 .env 파일을 수정해도 반영되지 않는다. 다시 빌드해야 한다.

포트 중복 확인

포트 3000이 이미 쓰이고 있을 수 있다.

# 포트 3000을 쓰는 프로세스 찾기
lsof -i :3000

# 또는
ss -lntp | grep 3000

# 프로세스 종료
kill -9 <PID>

포트가 막혀 있으면 다른 포트로 시작하거나, 기존 프로세스를 종료한다.

환경 변수 로드 순서

어떤 환경 변수를 먼저 로드하는가?

# 1순위: 명령줄 인자
PORT=4000 npm start

# 2순위: 시스템 환경 변수
export PORT=3001
npm start

# 3순위: .env 파일
# .env에 PORT=3000이라고 씀

# 결과: 4000으로 시작한다 (명령줄이 최우선)

로컬과 운영 비교

로컬에서는 되는데 배포 후에 안 될 수 있다. 배포 서버가 환경 변수를 다르게 설정했을 수 있다.

# 배포 서버에서 확인
echo $PORT
echo $NODE_ENV

# 또는 애플리케이션 로그에서
grep "PORT" /var/log/app.log

최종 확인: 앱 시작 로그

앱이 시작될 때 현재 설정을 출력하게 한다.

const port = process.env.PORT || 3000;
const env = process.env.NODE_ENV || 'development';

console.log(`\n=== App Starting ===`);
console.log(`Environment: ${env}`);
console.log(`Port: ${port}`);
console.log(`API URL: ${process.env.API_URL}`);
console.log(`===================\n`);

app.listen(port);

시작할 때마다 이 로그를 보면 설정이 제대로 로드되었는지 명확하다.

마지막으로, 환경 변수 문제는 대부분 로드 시점 또는 파일 위치 때문이다. 앱 시작 시 명시적으로 환경 변수를 출력하는 습관이 가장 효과적이다.