서버 배포 후 로컬에서는 없던 에러가 날 때

로컬에서는 완벽하게 작동하던 Next.js 앱이 서버에 배포되자마자 500 에러가 날 때가 있다. 이는 개발 환경과 프로덕션 환경의 차이 때문이다. 단순히 번그가 아니라 설정, 데이터, 네트워크 환경 모두를 점검해야 한다.

배포 서버의 에러 로그 확인하기

가장 먼저 할 일은 서버의 실제 에러 메시지를 보는 것이다. 브라우저에 나오는 "Internal Server Error"는 대증상일 뿐이다.

# 프로덕션 서버에서
ssh user@server
sudo journalctl -u your-app.service -n 50
cat /var/log/your-app/error.log

구체적인 에러 메시지가 나오면 원인을 파악할 수 있다. 예를 들어 "Cannot find module" 에러면 빌드 결과에 파일이 누락된 것이고, "ECONNREFUSED" 면 데이터베이스 연결에 실패한 것이다.

환경 변수 확인

배포 과정에서 환경 변수가 누락되거나 잘못 설정되는 경우가 많다.

# 프로덕션 서버에서
echo $DATABASE_URL
echo $API_KEY
# .env.production 파일 확인
cat /app/.env.production | head

특히 .env 파일은 git에 커밋되지 않으므로, 배포 시 수동으로 복사하거나 CI/CD 파이프라인에서 주입해야 한다. 이 단계를 빠뜨렸다면 앱이 제대로 작동할 수 없다.

데이터베이스 연결 테스트

서버의 데이터베이스 호스트, 포트, 인증 정보를 다시 확인한다.

# 데이터베이스 연결 테스트
mysql -h $DB_HOST -u $DB_USER -p$DB_PASSWORD -e "SELECT 1;"
# PostgreSQL인 경우
psql -h $DATABASE_HOST -U $DATABASE_USER -d $DATABASE_NAME -c "SELECT 1;"

로컬에서는 localhost:5432로 연결되지만, 서버에서는 다른 주소여야 한다. 특히 Docker 컨테이너를 사용한다면 네트워크 설정이 중요하다.

Node 버전과 의존성 확인

로컬과 프로덕션 서버의 Node 버전이 다를 수 있다. 특히 네이티브 모듈을 쓰는 패키지는 버전 차이에 민감하다.

# 로컬과 서버에서 실행
node --version
npm --version

# 서버에서
cd /app
npm install --production
npm run build

빌드 결과 검증

프로덕션 빌드가 완전한지 확인한다.

# 서버에서
ls -la /app/.next
ls -la /app/public

.next 디렉토리가 있고 .next/server 폴더가 비어있지 않은지 확인한다. 빌드가 실패했거나 불완전하면 이 디렉토리가 없을 수도 있다.

로컬에서 프로덕션 모드 테스트

배포 전에 로컬에서 프로덕션 모드로 한 번 실행해본다.

npm run build
npm start
# http://localhost:3000 접속

이렇게 하면 빌드 과정의 에러나 런타임 에러를 미리 발견할 수 있다.

체크리스트

1. 서버의 애플리케이션 로그를 확인한다. 구체적인 에러 메시지를 찾는다.
2. 프로덕션 환경 변수가 올바르게 설정되었는지 확인한다.
3. 데이터베이스 연결을 테스트한다.
4. Node와 npm 버전을 확인한다.
5. 의존성을 새로 설치하고 빌드한다.
6. 로컬에서 프로덕션 모드로 미리 테스트한다.

프로덕션 에러는 대부분 환경 차이에서 비롯된다. 로그, 환경 변수, 연결 테스트를 차례로 확인하면 원인을 찾을 수 있다.