[중급] Netlify 빌드 실패? 이 한 줄이면 99% 해결됨 (Node.js 버전 문제)

결론은, Node.js 버전 문제다.

어제 새벽 3시까지 이것 때문에 멘탈 나갈 뻔했다. 로컬에서는 멀쩡하게 돌아가던 프로젝트가 Netlify에만 올리면 귀신같이 빌드 실패. 로그를 까봐도 속 시원한 답은 안 나온다. 대부분 이런 메시지만 뱉어낼 거다.

Error running command: Build script returned non-zero exit code: 1
Failed during stage ‘building site’: Build script returned non-zero exit code: 1
Build failed due to a user error: Build script returned non-zero exit code: 1

저 ‘non-zero exit code: 1’이라는 건, 그냥 ‘뭔가 잘못됐는데 정확히는 나도 모름’ 수준의 무책임한 메시지다. 직장인 개발자 열에 아홉은 여기서 시간을 허비한다. 원인은 간단하다. 내 컴퓨터(로컬)와 Netlify 서버의 Node.js 버전이 달라서 생기는 참사다.

흔히 저지르는 5가지 삽질

이 에러를 만나면 보통 이런 순서로 삽질을 시작한다. 내가 직접 겪은 순서다.

1. ‘Retry with latest branch’ 무한 클릭: ‘혹시 일시적인 서버 오류 아닐까?’ 하는 희망으로 재배포 버튼만 누른다. 당연히 안 된다. 기계는 거짓말을 안 한다.
2. package.json 의심하기: 내 프로젝트에 설치된 라이브러리 버전이 꼬였나 싶어서 npm install, yarn install을 다시 해본다. 로컬에선 잘만 돌아가니 이것도 답이 아니다.
3. 빌드 명령어 수정: Netlify 빌드 설정에 들어가서 `CI=false npm run build` 같은 이상한 명령어를 추가해본다. 근본 원인이 아니라서 임시방편일 뿐, 다른 에러를 낳는다.
4. 캐시 지우고 재배포: Netlify의 ‘Clear cache and deploy site’ 기능. 물론 이것도 해결책이 아니다. 문제는 캐시가 아니라 환경 그 자체에 있다.
5. 구글링의 늪: ‘Netlify build failed’로 검색하면 수십 개의 해결책이 나온다. 하지만 내 상황과 100% 맞는 케이스는 찾기 힘들다. 결국 시간만 태운다.

가장 확실한 해결책: 주문서(.nvmrc) 던져주기

Netlify 빌드 로봇에게 어떤 버전의 Node.js를 사용해서 내 프로젝트를 조립할지 명확하게 알려줘야 한다. 이걸 ‘주문서’라고 생각하면 편하다. 주문서 양식은 두 가지다.

1. 가장 권장하는 방법: `.nvmrc` 파일 생성

프로젝트의 가장 최상위 폴더(루트)에 `.nvmrc` 라는 이름의 파일을 하나 만든다. 그리고 그 파일 안에 내 로컬 Node.js 버전을 딱 한 줄 적어주면 끝난다.

먼저 내 컴퓨터의 Node.js 버전을 확인한다.

node -v

예를 들어 터미널에 `v18.17.1` 이라고 나왔다고 치자. 그럼 `.nvmrc` 파일 안에 아래 내용만 적고 저장한다.

v18.17.1

이 파일을 저장하고 깃허브에 푸시하면, Netlify는 이 파일을 보자마자 ‘아, 이 프로젝트는 Node.js 18.17.1 버전으로 조립해야 하는구나’ 하고 알아서 세팅을 바꾼다. 이게 가장 정석적인 방법이다.

2. 급할 때 쓰는 방법: Netlify 환경 변수 설정

파일 생성이 귀찮다면 Netlify 사이트에서 직접 설정할 수도 있다.

경로: `Site settings` → `Build & deploy` → `Environment` → `Environment variables`

여기서 `Add a variable` 버튼을 누르고 아래와 같이 입력한다.

• Key: `NODE_VERSION`
• Value: `18.17.1` (v는 빼고 숫자만)

이렇게 해도 해결은 되지만, 프로젝트 코드와 인프라 설정이 분리된다는 점에서 추천하지 않는다. 팀원이 바뀌거나 다른 서버로 이전할 때 이 설정을 놓치기 쉽다. 설정은 언제나 코드와 함께 가야 한다.

핵심 요약

Netlify 빌드 실패는 99% 환경 불일치 문제다. 특히 Node.js 버전. 내 컴퓨터에서 쓰는 버전이랑 Netlify 서버에 설정된 버전이 같은지부터 확인하는 습관을 들여야 한다. `.nvmrc` 파일 하나면 이 모든 삽질을 끝낼 수 있다. 이거 하나 기억하면 된다.

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