yarn 버전으로 고통받는자는 Corepack을 연구해보자

2025. 1. 14. 11:22

다양한 팀과 함께하는 플젝과, 다른 버전의 yarn을 써야할때....
아마 프로젝트마다 다른 Yarn 버전을 써야 한다는 고민에 부딪히셨을 텐데, 바로 그럴 때 Corepack을 활용하면 꽤 편리하게 관리할 수 있습니다.

1. Corepack이란?

Corepack은 Node.js 16.9.0 이후 버전에 기본 탑재되어 있는 패키지 매니저 관리 툴입니다.

즉, “이 프로젝트에서는 Yarn 4.6.0을, 다른 프로젝트에서는 Yarn 1.22.19를” 쓰는 식의 버전 관리를 쉽게 해주는 도구입니다.

프로젝트 루트에 (또는 저장소에) packageManager 필드를 명시이렇게 해두면, 해당 프로젝트에 들어가서 yarn 명령어를 실행할 때
“Corepack이 자동으로 해당 버전(Yarn 4.6.0)을 사용”하게 됩니다.
코드 복사

// package.json { "name": "my-project", "packageManager": "yarn@4.6.0", ... }
jsonc
Corepack은 “shim” 방식으로 동작
- CLI에서 yarn --version 같은 걸 쳤을 때, Corepack이 중간에서 “아, 이 프로젝트의 package.json에는 Yarn 4.6.0을 쓰라고 되어 있네?”라고 인식하고, 그 버전을 다운로드/캐싱 후 실행해 줍니다.
- 사용자는 별도로 Yarn을 글로벌 설치할 필요 없이, 프로젝트에 적힌 버전 그대로 사용 가능합니다.
**corepack enable**만 해주면 OK
- 한 번만 설정해두면 Node가 설치된 환경에서 Corepack이 항상 동작하게 됩니다.
- 또는 Node 18 이상 버전에서는 이미 Corepack이 기본 활성화된 상태인 경우도 있습니다(환경마다 다를 수 있음).

프로젝트마다 다른 Yarn(혹은 pnpm, npm) 버전을 확실히 고정할 수 있음
- 협업 시, “내 로컬에서는 Yarn 1.22.19인데, CI나 다른 사람은 Yarn 4.6.0이네?” 같은 문제를 줄여줍니다.
개발자 로컬 환경 세팅이 간단
- 기존에는 “Yarn 버전 맞춰 설치해” 라고 문서로만 알려주거나, npm install -g yarn@4.6.0 같이 해줘야 했는데,
- Corepack을 쓰면 git clone 받은 뒤 Node 버전만 맞추면, 자동으로 Yarn 4.6.0이 깔려서 동작합니다.
Node.js 팀에서 공식적으로 지원
- 외부 도구(예: Volta, NVM 등)와 달리 Node.js에서 공식적으로 권장하는 방식이 되어가고 있습니다.
- 장기적으로 npm, Yarn, pnpm 등 메이저 패키지 매니저를 일관되게 사용할 수 있게 해 줍니다.

bash

코드 복사

# Node 16.9~16.13 사이 버전이라면 한 번만 실행 corepack enable

jsonc

코드 복사

{ "name": "my-project", "version": "1.0.0", "packageManager": "yarn@4.6.0", "scripts": { "start": "yarn dev" } }

이렇게 넣어두면, 해당 프로젝트 내에서 yarn을 치면 Yarn 4.6.0이 사용됩니다.
만약 다른 프로젝트에선 "packageManager": "yarn@1.22.19"를 적어두면, 그 프로젝트에선 Yarn 1.22.19가 실행됩니다.

package.json에 packageManager가 명시돼 있으므로,
- CI나 다른 팀원이 git clone -> yarn을 실행할 때, Corepack이 알아서 맞는 Yarn 버전을 다운로드하여 사용합니다.
CI에서도 Node 버전만 맞춰두면(예: Node 16.13 이상), “Yarn 버전 불일치” 문제가 사라집니다.

Volta
- Node, npm, Yarn 등 “런타임 및 패키지 매니저 버전”을 고정·자동 설치해주는 툴입니다.
- Corepack과 달리 Node도 원하는 버전으로 관리할 수 있고, 사용자의 글로벌 환경에 훨씬 세밀하게 커스텀 가능합니다.
- 개발자 로컬에 Volta를 설치해두면 .volta 파일이나 package.json 설정으로 버전 동기화가 가능합니다.
NVM(Node Version Manager)
- Node 버전을 설치/전환해주는 유틸이지만, npm 버전이나 Yarn 버전은 자동으로 고정하지 못합니다(별도로 설치).
- Node 버전에 따라 npm 버전이 달라지긴 하지만, Yarn은 별도입니다.
Yarn 2+ 자체 기능
- Yarn Berry는 .yarnrc.yml에 yarnPath: .yarn/releases/yarn-4.6.0.cjs처럼 지정하여,
  저장소 내부에 Yarn 바이너리를 커밋할 수도 있습니다(Zero-Install 방식).
- 이렇게 하면 Corepack 없이도 “프로젝트에 종속된 Yarn 버전”을 사용할 수 있습니다.
- 다만, 바이너리를 리포지토리에 커밋해야 한다는 단점이 있습니다.
npm scripts에서 npx yarn@4.6.0
- 사실상 임시 방편으로, npx yarn@4.6.0 install처럼 특정 버전 Yarn을 강제 실행할 수도 있습니다.
- 반복될 때마다 매번 Yarn을 다운로드하기에 비효율적이고, 팀원 간 버전 유지가 번거로우므로 일반적으로 추천되진 않습니다.

Corepack은 Node.js가 공식적으로 제공하는 “패키지 매니저 버전 관리 도구”로,
프로젝트마다 다른 Yarn(또는 npm, pnpm) 버전을 지정해도 자동으로 해당 버전을 사용하도록 만들어줍니다.
여러 팀·프로젝트를 동시에 다룰 때, 프로젝트마다 packageManager 필드를 달리 설정해두고,
**모든 협업자가 corepack enable**만 해 두면 버전 충돌 없이 Yarn을 사용할 수 있게 됩니다.
대안으로 Volta, NVM, Yarn Berry의 내장 기능(커밋된 Yarn 바이너리) 등이 있지만,
가장 간단하고 “공식적”인 방식은 최근엔 Corepack이 되어가고 있습니다.

따라서, 팀 전체가 Node 16.9+ 환경이라면 Corepack을 적극 도입해보시는 걸 추천드립니다!