TypeScript unknown 타입 처리로 막힐 때

TypeScript를 사용할 때 가장 짜증 나는 에러 중 하나는 unknown 타입 문제다. 코드는 로직적으로 맞는데, 타입 체커가 계속 경고를 낸다.

문제를 크게 잡지 말기

"어딘가의 타입이 unknown이라 에러가 난다"는 너무 넓다. 정확한 파일과 정확한 줄을 찾아야 한다.

먼저 재현 조건 파악하기

빌드할 때 나타나는가? 타입 체크할 때만 나타나는가? 런타임에는 정상인가?

npm run build

에러 메시지를 정확히 읽자. 어느 파일의 몇 번 줄에서 나는 에러인가?

서버와 로컬의 설정 차이

로컬에서는 안 나는데 빌드 서버에서만 나는 에러일 수도 있다. TypeScript 버전, tsconfig.json, 환경 변수가 다를 수 있다.

타입 정의 좁혀나가기

unknown 타입이 나타나는 시점을 역추적한다. 어디서부터 타입 정보가 사라졌는가?

함수가 반환하는 타입을 명시적으로 정의하고, 입력 파라미터의 타입도 명확히 한다. 타입 가드를 추가해서 unknown을 string, number 같은 구체적인 타입으로 좁혀나간다.

한 단계씩 수정하고 검증하기

한 곳의 타입을 고치고 다시 빌드한다. 에러가 줄었는가? 그럼 그 방향이 맞다. 다음 에러로 넘어간다.

수정 전후로 어떤 값이 달라졌는지 설명할 수 있으면, 진정 문제를 푼 것이다. 에러만 없애는 것보다는 왜 타입 에러가 났는지 이해하는 게 중요하다.