Vercel 빌드 오류 확인 및 해결방안

✏️ 개요

 

Vercel을 통해 배포를 하다보면 빌드에러를 마주치곤 한다.

 

VScode와 같은 코드 편집기에서 브랜치에 push 전 빌드에러를 미리 확인한다면 다행이겠지만, 때로는 VScode에서 발견되지 않는 에러들이 종종 발생하곤 한다.

 

Vercel에 대한 기본 정보나 장단점의 경우 내 글을 참고하고, 이 글을 통해서 빌드가 발생하는 상황과 해결방안을 도모해보자.

 

2025.05.27 - [코딩] - Github 다른 브랜치 vercel 배포

Github 다른 브랜치 vercel 배포

 

 

❌ 에러 확인

 

먼저, build 에러가 발생하는 상황에 대한 감지는 간단하다.

 

1. 배포된 페이지로 확인

처음 배포하는 상황이 아니라면, 원하는 브랜치에 push 이후, 기존 접속한 페이지 접속 시 에러가 발생할 것이다.

 

 

 

2. 깃허브 내에서 확인

내가 vercel에서 배포한 상황이라면 친절하게 최근 브랜치 커밋 내역 옆에 빌드 성공여부를 나타내거나,

우측 하단, Deployments에서도 성공여부를 확인할 수 있다. 

 

 

 

 

3. Vercel 대시보드에서 상황

1, 2번 상황모두 결국 에러의 이유를 확인하기위해 거쳐야하는 만남의 광장으로 대시보드라는 이름에 걸맞게 언제 어떤 브랜치에서 오류가 발생했는지를 확인 할 수 있다.

 

 

공통 : 빌드 에러 이유 확인

위 대시보드에서 원하는 작업/브랜치를 클릭할 경우 빌드 log를 볼 수 있고, 어디서 에러가 발생했는지 확인이 가능하다.

 

 

Build 상태가 Error이기 때문에 원래 좌측 상단에 보여야할 미리보기가 빌드에러로 대체되었고, 빌드 몇초중에 에러가 발생했는지도 확인 가능하다.

 

하단 Build Logs가 결국 빌드 실패에 대한 단서를 제공하기에 저 부분을 집중해서 보면 되는데, 발생한 경로, 에러메세지를 집중하면 에러내용을 찾기 쉽다.

 

 

나의 경우 Component의 위치를 바꾸고 해당 컴포넌트를 사용하는 파일에서 import 경로를 수정하지 않아 빌드에러가 발생했다.

 

위와 같이 직관적인 빌드에러에 대한 이유가 명시되어 있다면, 해결이 간단하나 가끔은 긴가민가한 메세지와 함께 어디서 잘못된건지 모르겠을 때가 존재한다. 

 

어떤 상황들이 있는지 확인해보자.

 

 

❌ 에러 상황 및 해결

 

1. 환경변수 미 기입

 

의외로 많이 발생하는 이슈로  IDE내에선 .env와 같은 파일을 통해 환경변수를 관리하지만, 깃허브에는 업로드되지 않기에 Vercel에서 배포전 환경변수에 대한 정보를 기입해주어야 한다.

 

Vercel의 Projects Settings 탭에서 Environment Variables에서  .env.local에 있는 모든 환경변수를 Key-Value로 등록하면 된다.

 

 

상단에 새로운 key, Value입력 시 아래와 같이 추가된다.

 

추가로, 설정 이후 재배포를 해야 적용되기에 새로운 변경내역이 있다면 브랜치에 push해서 재 배포해도 좋고, 따로 변경 내역이 없다면 동일 브랜치를 다시 배포하는 방법도 있다.

 

 

2. 패키지/의존성 충돌

 

자주 발생하지 않는 상황으로, 보통 협업을해서, 각 팀원 간 package.json, lock.json의 버전차이가 존재하거나, 프로젝트의 필요이유로 --force 옵션으로 설치 시 발생하곤 한다.

 

제일 좋은 방법은 팀원들과 회의 시간을 가져 package-lock.json을 비교하고 서로의 패키지 버전을 맞추는게 중요하지만, 급하게 확인해야 하거나 혼자 작업중이라면 최신 버전으로 통일하는 것도 한 방법이다.

 

npm install --legacy-peer-deps // 일시적으로 충돌을 우회할 수 있으나
// node_modules`, `package-lock.json` 삭제 후 재설치로 캐시 문제를 해결

 

 

 

3. 서버/클라이언트 컴포넌트 혼동

 

보통 IDE내에서도 해당 이슈는 발견되지만, 발견되지 않고 성공시키는 경우가 있어 확인이 필요하다.

 

예를들어 useSearchParams()훅을 서버 컴포넌트에서 사용하지는 않았는지 서버/클라이언트 컴포넌트간의 중첩구조가 문제가 없는지에 대한 확인이 필요하다.

 

 

4. 파일 및 폴더 대소문자 불일치

 

상단에 인덱싱에 있는 파일명의 경우 CommonCalendar인데 불구하고 아래 참조의 경우 COmmonCalendar로 되어있다.

 

때로, 파일명을 변경해도 대소문자만 바뀐경우 변경내용으로 감지 못하는 경우가 종종 있다. 이런 경우 빌드에러가 발생하곤 한다.

 

원인은 Windows나 macOS(기본 설정)는 파일 시스템이 대소문자를 구분하지 않지만, Vercel(리눅스 기반)은 대소문자를 엄격히 구분한다.

 

import 경로의 대소문자와 실제 파일명이 다르면 로컬에선 문제없어도 Vercel에서는 “module not found” 에러가 발생한다.

 

따라서, TS를 사용중이라면 tsconfig.json의 forceConsistentCasingInFileNames 옵션을 true로 설정해 대소문자 불일치 오류를 사전에 방지할 수 있다.

 

 

5. api 요청 중 에러가 발생하는 경우

 

이것도 꽤나 빈번한 상황으로 필자의 경우 프로젝트 중반 api 연결 단계에서 해당 에러를 많이 겪었다.

 

 

다음과 같은 유사 문구를 볼 수 있는데 주로 해당 api 요청을 관리자 모드로 보면 (대기중) 상태로 남아있다.

 

SSR을 사용한 경우 Vercel의 빌드단계에서 데이터 페칭을 진행하기에 일정시간 (10~60)초 보다 오래걸리는 경우 에러를 발생시키는 것이다.

 

해결방안으로는 다음과 같다.

 

1. api 완성되기 까지, 임시적으로 데이터 페칭 로직 대신 mock 데이터를 사용해 구현하기

2. api 페칭이 불가해도, 대체 로직 혹은 UI가 존재하는 경우 SSR이 아닌 CSR을 통해 useEffect을 통해 api 페칭로직 사용 시, 빌드 에러를 피할 수 있다. -> 빌드 단계가 아닌 배포 사이트 접속 후, 클라이언트 브라우저 측에서 요청하기에 문제 X

3. 서버리스, 혹은 규모가 작은 서버를 사용해, 단순히 응답속도가 느린 것이라면 Vercel 비싼 요금제를 사용해보자

-> pro, enterprise의 경우 대기 시간이 늘어남

 

빌드에러를 현명하게 해결하기 위해선 작업내용을 많이 쌓아두고, 배포 후 지켜보는게 아닌 작업내용을 잘게 쪼개 매번 확인하는 것이 어디서 내가 잘못했는지에 대한 추적이 좀 더 간단해질 수 있다.

 

📕 참고

https://vercel.com/docs/deployments/troubleshoot-a-build

Troubleshooting Build Errors