[트러블 슈팅] 로컬은 되는데 CI는 왜 안 되죠?(react-hook-form 빌드 오류 디버깅)

 

평소처럼 PR을 보냈는데 갑자기 Github Actons에서 타입 에러로 빌드가 실패하는 일이 발생했습니다.

그래서 해당 포스트에서는 빌드 오류를 해결한 내용에 대해 정리해보려고 합니다.

 

발생한 오류 🔥

기존에 정상적으로 빌드되먼 PR이 갑자기 GitHub Actions에서 빌드 실패 문제가 발생했습니다.

로컬에서는 동일한 코드가 정상 빌드가 됐고 오류 위치는 `react-hook-form`의 `watch()` 함수 사용 부분에서 오류가 발생했습니다.

 

타입 오류

 

해결 과정 🔎

1. 로컬 vs CI 환경 비교

항목	로컬	Github Actions (CI)
yarn.lock	✅ 존재	❌ 존재하지 않음 (.gitignore에 포함 됨)
react-hook-form 버전	7.43.5 또는 7.58.1	7.61.0 (최신 패치 자동 설치됨)
빌드 결과	정상	타입 에러 발생

 

 

2. 재현을 위한 시도

빌드 오류가 단순한 캐시 문제인지 확인하기 위해, 코드에 의미 없는 주석만 추가해서 PR을 생성했는데 여전히 빌드 오류 발생

빌드 실패

 

❗여기서 단순한 캐시 이슈가 아닌, 환경에 따라 설치되는 라이브러리 버전이 달라진다는 직감이 들기 시작했다.

 

 

3. 의존성 버전 확인(react-hook-form)

로컬과 CI의 설치 버전 차이 확인

실제 설치 된 버전 확인

 

💡그래서 react-hook-form 공식 문서 테스트 코드 확인

 

7.58.1 버전의 form 관련 테스트 코드를 확인해 봤을 땐 watch에 반환 타입 `T | undefined`에 대한 테스트 코드 확인 불가

react-hook-form/src/__typetest__/form.test-d.ts at v7.58.1 · react-hook-form/react-hook-form

 

 

혹시나 하는 마음에 최신 버전 문서에 form 타입 관련 테스트 코드 파일을 확인했을 때 기본 값이 없을 때 `T | undefined` 테스트를 반환하는 것으로 확인

react-hook-form/src/__typetest__/form.test-d.ts at master · react-hook-form/react-hook-form

expectType<number | undefined>(form.watch('id'));
expectType<number>(form.watch('id', 4711));

 

4. 발견한 문제

react-hook-form 공식 문서

 

✅ react-hook-form@7.61.0 릴리스 시점

• 7월 23일 밤에 릴리스됨 (GitHub 기준 13시간 전) 이 버전에서 watch()의 타입 처리 방식 변경됨

❌ GitHub Actions 빌드 오류

• CI에서 yarn install 할 때 package.json의 "^7.43.5"를 따라가면서 최신 버전(7.61.0)을 설치
• watch() 함수의 반환 타입이 T | undefined로 강화되면서 타입 에러 발생

 

그럼 왜 로컬은 괜찮았을까 ❓

• 로컬에는 yarn.lock과 node_modules가 이미 존재했기 때문에
• 따라서 react-hook-form의 하위 버전이 그대로 유지되었고 타입 문제가 발생하지 않았던 것임!

 

5. 결론 요약

CI 환경에서는 `yarn.lock` 파일이 없고 `^` 버전 때문에 의존성이 CI에서는 최신 버전이 설치되면서 watch() 함수 타입에서 오류가 발생했던 것 이였습니다.

 

 

해결 방법 ✨

• .gitignore에서 yarn.lock 제거 → Git에 포함시킴
• package.json에서 react-hook-form을 "7.58.1"로 버전 고정
• GitHub Actions에서 yarn install --frozen-lockfile 옵션 추가

name: Install dependencies
run: yarn install --frozen-lockfile

 

어려웠던 점 ❓

로컬에서는 문제가 안 보이니 처음엔 문제 인지를 못 했고, 단순 캐시 문제로 오해하는 상황이 생겼습니다.

그리고 `react-hook-form`의 타입 변경이 마침 전날 배포된 상태라 문제를 파악하기 더 혼란스러웠던 것 같습니다.

 

회고 🧐

이번 경험으로 CI 환경에서도 의존성 일관성 확보가 얼마나 중요한지 다시 한번 체감했습니다.

 

 

아직 많이 부족하기 때문에 조언은 언제나 환영입니다 ~!

:)

---