타입 에러로 빌드가 막릴 때 빠르게 좁히는 법

웹 개발 프로젝트에서 npm run build를 했을 때 타입 에러가 나면 화면이 가득 찬 에러 메시지에 좌절할 수 있다. 하지만 체계적으로 접근하면 대부분의 타입 문제는 몇 가지 원인에서 비롯된다.

빌드 에러 메시지 보는 순서

먼저 에러 메시지의 처음 부분만 본다.

npm run build 2>&1 | head -50

대부분의 경우 처음 에러가 이후 에러들의 원인이다. 나머지는 연쇄 반응일 가능성이 높다.

에러 파일과 줄 번호 확인

에러 메시지에서 파일 경로와 줄 번호를 먼저 적어둔다.

error TS2322: Type 'string' is not assignable to type 'number'.
  at src/components/Button.tsx:23:5

이 정보만으로 해당 파일을 열고 그 줄을 봐도 원인을 찾을 수 있다.

타입 오류의 일반적인 원인

• 환경 변수 타입 안 맞음: .env 파일에 있는 값이 의도한 타입과 다를 때
• 외부 라이브러리 버전 차이: node_modules에 설치된 버전이 예상과 다를 때
• tsconfig 설정: strictNullChecks 같은 엄격한 옵션이 켜져 있을 때

빠른 확인

npm run build 2>&1 | grep -A 2 "error TS"

이 명령어로 타입 에러만 필터링해서 본다. 그리고 가장 먼저 나온 에러부터 하나씩 고치면 된다.