#prompt_included Yarn 버전 비호환 해결하기: 레거시 1.x에서 최신 4.x로 업그레이드

최신 웹 개발 프로젝트를 다루다 보면 의존성 관리 도구가 빠르게 바뀌고, 버전 호환성 문제가 순식간에 걸림돌이 되곤 합니다. 얼마 전 저도 흔하지만 짜증 나는 문제를 만났습니다. 프로젝트는 Yarn 4.6.0 이상을 요구하는데, 제 시스템에는 레거시 버전인 1.22.19가 깔려 있었던 것입니다.

문제 상황

최신 Yarn 기능에 의존하는 프로젝트의 의존성 관리 스크립트를 실행하려는 순간 문제가 드러났습니다. 프로젝트의 package.json 파일에는 엄격한 버전 요구 사항이 지정되어 있었습니다.

{
  "engines": {
    "yarn": ">= 4.9.3",
    "node": ">= 20.0"
  },
  "packageManager": "yarn@4.9.3"
}

오류 메시지는 명확했지만 반갑지는 않았습니다.

The engine "yarn" is incompatible with this module. Expected version ">= 4.9.3". Got "1.22.19"

이 프로젝트가 최신 Yarn 기능을 필요로 한 명령은 다음과 같습니다.

yarn install

하지만 요구되는 Yarn(4.6.0 이상)과 설치된 버전(1.22.19)이 맞지 않아, 시작부터 프로젝트 개발이 가로막혔습니다.

버전이 중요한 이유

Yarn은 메이저 버전마다 큰 변화를 겪었습니다. 1.x는 "클래식" Yarn이고, 2 이상(지금은 "모던" Yarn 또는 "Berry"라고 부릅니다)은 아키텍처가 크게 개선되었고, 워크스페이스 지원이 강화되었으며, 보안 기능도 좋아졌습니다. 요즘 많은 프로젝트가 이런 고급 기능 때문에 모던 버전을 요구합니다.

Yarn 1.x에서 모던 버전으로 넘어가면 다음과 같은 핵심 개선을 얻을 수 있습니다.

  • 모노레포를 위한 더 나은 워크스페이스 관리
  • 더 빠르고 안정적인 설치를 위한 Plug'n'Play 설치 방식
  • 더 나은 패키지 검증으로 강화된 보안
  • 개선된 의존성 해석 알고리즘

실패한 시도들

해결책을 찾기 전에, 흔히 쓰는 방법 몇 가지는 권한 제한 때문에 모두 실패했습니다.

  1. npm 전역 설치 - 권한 거부 오류로 시스템 전체 패키지 관리가 불가능했습니다
  2. 공식 Yarn 설치 프로그램 - 설치가 끝까지 완료되지 못하고 망가진 상태로 남았습니다
  3. Corepack - Node.js의 패키지 매니저 역시 권한 문제에 부딪혔습니다

이 실패에서 얻은 핵심 교훈이 있습니다. 특히 권한이 제한된 환경에서는 자동 설치 프로그램에 기대기보다 가장 직접적인 방법이 더 잘 통할 때가 있다는 것입니다.

통했던 해결 방법

성공한 방법은 Yarn을 직접 내려받아 수동으로 설정하는 것이었습니다.

1단계: 깨끗이 비우기

rm -rf ~/.yarn
mkdir -p ~/.yarn/releases

2단계: 직접 다운로드

curl -L https://repo.yarnpkg.com/4.9.3/packages/yarnpkg-cli/bin/yarn.js -o ~/.yarn/releases/yarn-4.6.3.cjs
chmod +x ~/.yarn/releases/yarn-4.9.3.cjs

3단계: 설정

~/.yarnrc.yml 파일을 만들거나 수정합니다.

echo "yarnPath: ~/.yarn/releases/yarn-4.9.3.cjs" > ~/.yarnrc.yml

또는 

echo "yarnPath: /home/$USER/.yarn/releases/yarn-4.9.3.cjs" > ~/.yarnrc.yml

4단계: 확인

yarn --version

5단계: 설치 테스트

yarn install

성공 지표

이 해결책을 적용한 뒤의 결과입니다.

  • ✅ Yarn 버전을 1.22.19에서 4.9.3으로 성공적으로 업그레이드
  • ✅ 프로젝트 의존성 설치가 오류 없이 실행됨
  • ✅ NPM 패키지가 모던 Yarn으로 문제없이 관리됨
  • ✅ 호환성 문제나 큰 경고가 전혀 발생하지 않음

모던 Yarn 생태계 이해하기

Yarn 4.6.0을 설치하면 다음과 같은 최신 기능을 쓸 수 있습니다.

개선된 패키지 관리: 모던 Yarn은 피어 의존성을 더 잘 처리하고 패키지 해석도 더 안정적입니다.

워크스페이스 지원: 패키지 간 의존성 처리가 개선되어 모노레포를 더 잘 관리할 수 있습니다.

보안 강화: 더 나은 패키지 검증과 더 안전한 설치 과정을 제공합니다.

성능 향상: 개선된 캐싱 전략 덕분에 설치 시간이 짧아지고 디스크도 더 효율적으로 쓸 수 있습니다.

핵심 정리

직접 내려받는 쪽이 자동 설치 프로그램보다 더 믿을 만할 수 있습니다. 권한이나 시스템 충돌 때문에 패키지 매니저나 설치 프로그램이 실패한다면, 도구를 직접 내려받아 설정하는 편이 더 깔끔한 해결책이 되곤 합니다.

설정 파일은 강력합니다. Yarn의 .yarnrc.yml 설정 방식을 쓰면 시스템 전체를 바꾸거나 높은 권한을 얻지 않고도 유연하게 버전을 관리할 수 있습니다.

최신 웹 개발에서는 버전 호환성이 결정적입니다. 도구가 빠르게 진화하는 만큼, 버전 요구 사항을 늘 파악하고 믿을 만한 업그레이드 전략을 갖춰 두는 일이 프로젝트를 이어가는 데 점점 더 중요해집니다.

기록은 힘이 됩니다. 성공한 해결 방법을 자세히 적어 두면 개발자 개인에게도 팀에게도 같은 해결을 효율적으로 재현하는 데 도움이 됩니다.

다른 대안들

수동 다운로드 방식이 여러분의 환경에서 통하지 않는다면 다음 대안을 고려해 보세요.

Node Version Manager(nvm) 사용: Yarn을 업그레이드하기 전에 먼저 호환되는 Node.js 버전을 쓰고 있는지 확인하면 해결되는 경우가 있습니다.

프로젝트 로컬 설치: 전역 설치 대신 각 프로젝트 디렉터리 안에 Yarn을 로컬로 설치하는 팀도 있습니다.

Docker 기반 개발: 로컬 환경 문제로 어려움을 겪는 팀이라면, 컨테이너화된 개발 환경이 팀원 모두에게 일관된 도구 버전을 제공해 줄 수 있습니다.

이번 경험은 의존성 관리에 여러 가지 전략을 마련해 두는 일이 얼마나 중요한지 다시 일깨워 주었습니다. 자동화 도구는 대개 잘 작동하지만, 수동으로 쓸 수 있는 대비책이 있으면 편리한 방법이 실패하더라도 개발 흐름을 이어갈 수 있습니다.

비슷한 Yarn 버전 충돌을 겪는 개발자에게, 이 수동 다운로드와 설정 방식은 자동 설치 프로그램을 대신할 믿을 만한 대안입니다. 특히 권한이나 시스템 설정 때문에 다른 업그레이드 경로가 막힌 환경에서 유용합니다.

다른 분들을 위한 프롬프트

같은 Yarn 버전 비호환 문제를 겪고 있다면, Claude code에서 이 프롬프트를 사용해 보세요.

### keep in a loop until it is working without errors
I want to manage a working run for `yarn install`
 but I keep getting a yarn version incompatibility error.
 
The error shows:

  yarn install v1.22.19
  [1/5] Validating package.json...
  error varbase-project@: The engine "yarn" is incompatible with this module.
   Expected version ">= 4.9.3". Got "1.22.19"
  error Found incompatible module.
  info Visit https://yarnpkg.com/en/docs/cli/install for documentation about this command.

I need to upgrade yarn from 1.22.19 to >= 4.9.3 and get my project working without errors.
Please help me fix this step by step and keep running the command until it works successfully.

Commands to follow with:
rm -rf ~/.yarn
mkdir -p ~/.yarn/releases
curl -L https://repo.yarnpkg.com/4.9.3/packages/yarnpkg-cli/bin/yarn.js -o ~/.yarn/releases/yarn-4.9.3.cjs
chmod +x ~/.yarn/releases/yarn-4.9.3.cjs
echo "yarnPath: ~/.yarn/releases/yarn-4.9.3.cjs" > ~/.yarnrc.yml  or echo "yarnPath: /home/$USER/.yarn/releases/yarn-4.9.3.cjs" > ~/.yarnrc.yml
yarn --version

또는 짧은 프롬프트 

 Follow with the Prompt for Others to use in https://natshah.com/node/162
Yarn logo on a gradient blue card about version compatibility.