[중급] Netlify ‘Build command failed’ 에러, 5가지 시나리오만 알면 끝난다

이것을 먼저 알아야 한다. 에러 메시지는 당신의 적이 아니다.

며칠 전 새벽까지 Netlify 배포 로그만 쳐다봤다. ‘Build command failed’. 이 붉은색 한 줄 때문에 커피를 몇 잔을 마셨는지 모른다. 초보 시절엔 이게 세상이 무너지는 소리처럼 들린다. 하지만 수백 번 배포 파이프라인을 터뜨려 본 입장에서 말하자면, 원인은 늘 어이없을 정도로 간단한 곳에 있다. 당신이 놓친 사소한 설정 하나 때문이다.

이 글은 Netlify 배포 실패로 밤새우는 사람들을 위한 실전 트러블슈팅 기록이다. 뜬구름 잡는 이론은 걷어내고, 내가 직접 겪었던 5가지 대표적인 시나리오와 해결책만 담았다.

‘Build command failed’의 5가지 그림자

배포 실패의 원인은 수십 가지가 넘지만, 직장인 열에 아홉은 아래 5가지 범주 안에서 넘어진다. 나도 그랬다.

1. Node.js 버전 불일치: ‘우리 집엔 없는데?’

가장 흔하고, 가장 허무한 실수다. 내 컴퓨터(로컬)에서는 최신 18.x 버전 Node.js로 잘만 돌아가던 프로젝트가, Netlify에 올리니 귀신같이 죽는다. 왜? Netlify의 기본 빌드 환경은 당신의 컴퓨터가 아니기 때문이다.

상황: 최신 자바스크립트 문법이나 특정 라이브러리가 낮은 버전의 Node.js에서 호환되지 않아 빌드 과정에서 문법 오류를 뿜어낸다.

해결책: Netlify 설정에 환경 변수를 추가하면 끝난다. ‘Site settings’ > ‘Build & deploy’ > ‘Environment’로 이동. ‘New variable’을 눌러 Key에 NODE_VERSION, Value에 당신이 로컬에서 사용하는 버전(예: ’18’)을 명시적으로 박아주면 된다. 이걸로 해결되는 경우가 절반이다.

2. 환경 변수 누락: ‘열쇠를 안 주고 문 열라는 격’

로컬 개발 환경에서는 .env 파일에 API 키나 DB 접속 정보 같은 민감한 데이터를 넣어두고 쓴다. 이건 깃허브에 올리면 안 되니 .gitignore에 등록해놓는다. 문제는 여기서 시작된다. Netlify는 당신의 .env 파일 존재 자체를 모른다.

상황: 빌드 스크립트가 process.env.API_KEY 같은 환경 변수를 찾으려 하는데, 값이 없으니 ‘undefined’가 되어버리고, 관련 로직 전체가 멈춘다.

해결책: 이것도 환경 변수 설정으로 해결한다. .env 파일에 있던 모든 키-값 쌍을 Netlify의 환경 변수 설정 UI에 하나하나 수작업으로 옮겨줘야 한다. 집 열쇠(API 키)를 나만 갖고 있고, 자동 청소 로봇(Netlify)한테는 안 준 꼴이다. 로봇이 일을 하려면 열쇠를 복사해줘야 한다.

3. 빌드 명령어 & 디렉토리 설정 오류: ‘엉뚱한 곳을 파고 있다’

Create React App은 npm run build를 실행하면 build 폴더에 결과물을 뱉어낸다. Vite는 dist 폴더에 만든다. 이 간단한 차이를 무시하면 Netlify는 빌드 후 어디서 파일을 찾아야 할지 몰라 헤맨다.

상황: 빌드는 성공적으로 끝났는데, Netlify가 ‘Deploy directory ‘build’ not found’ 같은 메시지를 띄우며 배포에 실패한다.

해결책: ‘Build & deploy’ 설정에서 ‘Build command’와 ‘Publish directory’를 당신의 프로젝트에 맞게 수정해야 한다. package.json 파일의 ‘scripts’ 부분을 열어보고, 빌드 명령어가 뭔지, 빌드 결과물이 어느 폴더에 생성되는지 직접 확인하는 습관을 들여야 한다.

4. 패키지 종속성 문제: ‘부품이 서로 안 맞는다’

내 컴퓨터에서는 npm install로 잘만 설치되던 패키지들이 Netlify의 깨끗한 빌드 환경에서는 충돌을 일으키는 경우가 있다. 특히 C++ 같은 네이티브 코드를 필요로 하는 패키지에서 자주 발생한다.

상황: 특정 패키지 설치 단계에서 에러가 발생하며 빌드 로그가 붉은색으로 도배된다. 혹은 로컬의 package-lock.json과 실제 설치되는 버전이 미묘하게 달라 문제가 생긴다.

해결책: 빌드 명령어를 npm install 대신 npm ci로 바꿔보는 게 좋다. npm ci는 package-lock.json 파일을 기준으로 정확히 동일한 버전의 패키지만 설치해서 예측 가능성을 높인다. 마치 조립 설명서에 적힌 부품만 정확히 사용하는 것과 같다. 이걸로도 안 되면, 문제 되는 패키지가 Netlify의 빌드 환경(리눅스 기반)과 호환되는지부터 확인해야 한다.

5. 파일 경로 대소문자: ‘가장 악랄한 함정’

이건 당해본 사람만 안다. 윈도우나 맥OS는 기본적으로 파일 경로의 대소문자를 구분하지 않는다. 하지만 Netlify가 사용하는 리눅스 서버는 철저하게 구분한다. Header.js와 header.js는 완전히 다른 파일이다.

상황: 로컬에서는 아무 문제 없이 잘 보였던 이미지나 컴포넌트를 Netlify 서버가 찾지 못해 404 에러를 뱉고, 빌드 과정에서 ‘Module not found’ 에러가 발생한다.

해결책: 처음부터 파일과 폴더 이름을 지을 때 일관된 규칙(예: 전부 소문자, 혹은 컴포넌트만 대문자로 시작)을 정하고 철저히 지키는 것 외엔 왕도가 없다. 이미 엉망이라면, 깃이 대소문자 변경을 인식하도록 설정을 바꾸고 파일명을 하나씩 수정해야 한다. 가장 귀찮고 시간을 많이 뺏는 유형이다.

결론: 로그를 읽어라. 그 안에 답이 있다.

결국 배포 실패 로그를 읽는 능력이 핵심이다. 에러 메시지는 당신을 괴롭히는 게 아니라, 길을 알려주는 유일한 이정표다. ‘Build command failed’라는 결과만 보지 말고, 그 위에 출력된 수십, 수백 줄의 로그 속에서 ‘not found’, ‘error’, ‘failed’ 같은 키워드를 찾아내 원인을 추적해야 한다. 이 5가지 시나리오만 머리에 넣으면 웬만한 빌드 에러는 10분 안에 잡을 수 있다.

PipeMaster-Lab 운영정책 및 제보 안내