Next.js
Next.js 빌드가 실패할 때 처음 확인할 로그
API 타입 에러나 메타데이터 문제는 빌드 로그를 먼저 읽으면 90%는 바로 보인다.
Next.js 빌드가 실패하면 검색창에 에러 메시지를 먼저 붙여넣는 개발자가 많다. 하지만 대부분의 경우 빌드 로그에 정확한 원인과 해결책이 이미 적혀 있다. 처음 보는 에러라 해도 로그를 차근차근 읽는 게 가장 빠르다.
빌드 로그의 어느 부분을 봐야 할까
Next.js 빌드 출력을 보면 성공한 페이지들이 쭉 나열된 후 어디서 에러가 났는지 나타난다. 그 에러 부분부터 위로 올라가며 읽으면 된다. 보통 어느 파일에서, 어느 줄에서 뭐가 잘못됐다는 정보가 명확하게 나온다.
타입 에러는 빌드 타임에 잡기
TypeScript를 썼는데 빌드가 실패한다면 타입 불일치 가능성이 높다.
# 로컬에서 빌드해보기
npm run build
# TypeScript 컴파일만 실행
npx tsc --noEmit
메타데이터와 OG 태그 검증하기
API 라우트에서 메타데이터를 동적으로 생성하는데 빌드가 실패한다면, 보통 메타데이터 형식이 맞지 않거나 필수 필드가 빠진 것이다. 각 페이지의 <head> 태그를 확인해보자.
# 생성된 HTML에서 메타데이터 확인
curl -s https://example.com | grep -Ei 'title|description|canonical|og:|twitter:'
로컬과 배포 환경의 차이 알아두기
로컬에서 빌드는 성공하는데 배포 서버에서 실패할 수도 있다. 환경 변수가 다르거나, 빌드 과정에서 외부 API를 호출하는데 배포 환경에서 그 API에 접근할 수 없는 경우도 있다. 배포 서버의 빌드 로그를 따로 저장해두는 습관을 들이자.
빌드 에러는 한 가지씩 처리하기
빌드 실패 메시지가 여러 개 나타나도 가장 위의 첫 번째 에러부터 고치자. 뒤의 에러들은 대부분 첫 번째 에러의 연쇄 반응이다. 첫 번째를 고치고 다시 빌드하면 뒤의 에러들이 사라질 가능성이 높다.