앱 버전 충돌로 막힐 때 해결하기

개발할 때는 가지고 있는 의존성 버전 조합이 잘 작동하지만, 배포 후에는 버전 충돌로 문제가 생길 수 있다. 특히 처음부터 정답을 맞히려고 하면 오히려 확인 시간이 길어진다. 체계적으로 접근해야 한다.

현재 상태 정의

먼저 정상 상태를 명확하게 정해두는 것이 중요하다. 어떤 버전에서는 작동했고, 어떤 버전에서 안 되는지 알아야 한다.

현재 설치된 버전을 확인하자:

npm list
npm list react react-dom next

이 명령어로 의존성 트리와 버전을 볼 수 있다. 만약 같은 패키지의 여러 버전이 설치되어 있다면 문제가 될 수 있다.

빌드 결과 확인

실제 빌드가 성공했는지 확인해야 한다:

npm run build

WARN이나 ERROR 메시지가 있는지 주의 깊게 봐야 한다. 특히 버전 호환성 경고가 있을 수 있다.

package.json과 package-lock.json 비교

package.json에 정의된 버전과 실제로 설치된 버전(package-lock.json)이 다를 수 있다:

git diff package-lock.json

만약 변경이 많다면 누군가 의존성을 업그레이드했고, 호환성 문제가 생겼을 가능성이 높다.

설정 점검

주요 라이브러리의 설정이 현재 버전과 맞는지 확인하자. 예를 들어 Next.js의 경우:

cat next.config.js

오래된 설정이 최신 버전에서 deprecated되었을 수도 있다.

로그에서 볼 부분

빌드 로그와 런타임 로그를 자세히 읽자:

npm run build 2>&1 | tee build.log
cat build.log | grep -i "deprecat\|error\|warn"

특히 "deprecat"로 시작하는 메시지는 향후 버전에서 작동하지 않을 수 있다는 뜻이다.

호환성 확인

Package 버전 호환성을 확인하는 웹사이트가 있다:

• npm.js.org에서 각 패키지의 호환성 정보 확인
• GitHub의 릴리스 노트에서 breaking changes 확인

특히 major 버전이 올라갔다면 반드시 릴리스 노트를 읽어야 한다.

작게 바꿔보기

한 번에 여러 의존성을 업그레이드하지 말자. 하나씩 시도하면서 어디서 문제가 나는지 확인해야 한다:

npm install react@latest
npm run build

만약 이것이 실패하면 다른 패키지로 이동하기 전에 이것부터 해결해야 한다.

실패 시 복구

만약 뭔가 잘못되었다면, git으로 복구할 수 있다:

git checkout package.json package-lock.json
npm ci

또는 node_modules를 완전히 정리하고 다시 설치할 수도 있다:

rm -rf node_modules package-lock.json
npm install

다음에 남길 기록

버전 업그레이드 후에는 어떤 변경을 했는지, 무엇이 깨졌는지 기록해두자. 나중에 비슷한 상황이 나오면 훨씬 빠르게 대응할 수 있다.

1. 업그레이드한 패키지와 버전
2. 빌드나 런타임에서 나타난 에러
3. 실제 수정 방법
4. 테스트 결과

의존성 관리는 정기적으로 하는 것이 좋다. 한 번에 모든 것을 업그레이드하려고 하면 문제를 추적하기 어려워진다.