빌드가 로컬에서는 되는데 서버에서만 실패할 때

"로컬에서는 잘 돌아가는데 서버에서만 빌드가 실패한다"는 보고를 받으면 환경 차이를 의심해야 한다. 빠르게 원인을 찾는 체계가 필요하다.

서버의 빌드 로그 확인

가장 먼저 빌드 로그의 맨 끝을 본다. 에러 메시지가 뭔지 정확히 읽는다.

# 배포 도구의 로그 확인 (예: Vercel, Netlify)
# 또는 직접 서버에서
cat /var/log/build.log | tail -50

에러를 복사해서 검색하거나, 더 자세한 정보를 얻기 위해 빌드 명령을 다시 실행한다.

로컬에서 운영 조건으로 빌드 재현

로컬에서 서버와 같은 조건으로 빌드해본다:

# Node 버전 확인 - 로컬과 서버가 같은가?
node --version

# npm 버전도 확인
npm --version

# 의존성 다시 설치 (캐시 무시)
rm -rf node_modules
npm ci  # npm install 대신 ci 사용 (production 환경처럼)

# 프로덕션 빌드
npm run build

로컬에서도 같은 에러가 나면 원인을 파악하기 쉬워진다.

환경 변수 확인

서버에 필요한 환경 변수가 모두 설정되어 있나?

# 예상되는 환경 변수 목록 확인
grep -r 'process.env.' src/ | cut -d: -f2 | sort | uniq

빌드 시 process.env를 접근하는 코드가 있다면, 서버의 .env 파일이나 환경 설정에 모두 입력되어야 한다.

디스크와 메모리 확인

서버의 디스크나 메모리가 부족하면 빌드가 실패할 수 있다.

df -h  # 디스크 확인
free -h  # 메모리 확인

디스크가 95% 이상이거나 메모리가 부족하면 빌드가 중단될 수 있다.

Node 모듈 호환성

일부 패키지는 특정 Node 버전에서만 제대로 빌드된다. 서버의 Node 버전을 확인한다.

# 로컬의 Node 버전
node --version
# 출력: v18.12.0

# 서버에도 같은 버전 설치되어 있나 확인

Node 버전이 다르면 네이티브 모듈(C++ 바인딩이 있는 패키지)이 작동하지 않을 수 있다.

빌드 명령 재확인

package.json의 빌드 스크립트가 정확한가?

{
  "scripts": {
    "build": "next build"
  }
}

만약 빌드 전에 사전 작업이 필요하다면 (예: 타입 체크, 린트) 그것도 서버에서 실행되어야 한다.

한 가지씩 변경해서 테스트

여러 원인이 동시에 있을 수 있으니 한 가지씩 확인한다:

1. Node 버전만 맞춘다
2. 환경 변수만 설정한다
3. 디스크 공간만 확보한다

각 단계에서 빌드를 시도해서 어디서 문제가 해결되는지 본다.