빌드할 때만 나는 타입 에러 디버깅하기

빌드 과정에서 나타나는 타입 에러는 로컬 개발 환경과 빌드 환경의 차이에서 비롯되는 경우가 많다. 특히 unknown 타입으로 인한 에러는 처음에는 원인을 찾기 어려울 수 있다.

먼저 재현 조건 잡기

에러가 나는 상황을 명확히 하는 게 가장 중요하다. 로컬 개발 서버에서는 문제가 없었는데 빌드 명령을 실행할 때만 에러가 난다면, 빌드 도구나 타입스크립트 설정 차이를 의심해봐야 한다.

• 정확한 에러 메시지를 복사해두기
• 어떤 파일에서 언제 나타나는지 기록하기
• 로컬과 빌드 환경의 설정 차이 확인하기

타입 체크 단계에서 확인할 값

npm run build

이 명령을 실행할 때 정확히 어느 단계에서 멈추는지 봐야 한다. 보통 번들링 전에 타입스크립트 컴파일 단계에서 실패한다. 에러 메시지에서 파일 경로와 행 번호를 주목하면 원인 코드를 빠르게 찾을 수 있다.

일반론이 아닌 구체적 원인 찾기

타입 에러를 해결할 때는 한 가지만 고치지 말고 전체 흐름을 봐야 한다. 다음과 같이 좁혀나가는 게 효과적이다:

1. 에러 메시지의 정확한 라인 확인
2. 그 코드에서 사용하는 변수나 함수의 타입 확인
3. 해당 변수가 할당되는 모든 경로 확인
4. 로컬과 빌드 환경의 타입스크립트 설정 비교

수정 후 검증

한 번에 여러 곳을 고치지 않는다. 작은 수정 하나를 한 후 다시 빌드해본다. 그래야 어느 수정이 실제로 효과가 있었는지 알 수 있다.

로컬에서 타입 에러가 없다고 해서 빌드도 성공할 거라고 가정하지 마라. IDE는 별도의 타입 체킹을 하고 빌드 도구는 다른 설정을 사용할 수 있다. 이런 차이를 아는 것만으로도 다음 문제 해결이 훨씬 빨라진다.