[ Troubleshooting🛠️ ] 패키지 매니저 충돌 트러블 슈팅 npm, yarn, pnpm 간의 전환

1.  문제 발생❓

"pnpm install" 오류와 패키지 매니저 충돌

 Next.js 프로젝트 작업 중 Vercel에 배포하려고 했지만 pnpm install 명령이 실패하는 문제가 발생했습니다. 로컬에서는 일반적으로 npm을 사용하고 있었으나, Vercel에서는 pnpm을 사용하려고 시도하면서 충돌이 발생한 것 입니다.

 

 

2.  원인 추론 🔎

 

발단: 전역 패키지 매니저 설정

1. 초기 상황
   • 저는 전역으로 Yarn 패키지 매니저를 사용하고 있었습니다.
   • 프로젝트에서 자연스럽게 Yarn을 사용하게 되었고, Corepack의 자동 설정으로 packageManager 필드가 추가되었습니다.
2. 겉보기에는 문제없는 로컬 개발 환경
   • 로컬에서 Yarn으로 프로젝트가 잘 실행되었습니다.
   • 모든 것이 정상적으로 작동하는 것처럼 보였습니다.

배포 시 발생한 문제

 Vercel 배포 중 예상치 못한 오류가 발생했습니다:

• 배포 과정에서 "pnpm install" 오류 발생
• 프로젝트가 실제로는 pnpm을 기본 패키지 매니저로 사용하고 있었음을 알게 됨

이러한 증상은 여러 패키지 매니저 간의 충돌을 명확히 보여줍니다. 특히 Corepack이 관여하면서 상황이 더 복잡해졌습니다.

 

 

🌎 여기서 Corepack 이란?

 Node.js에 내장된 Corepack은 패키지 매니저의 버전을 관리하는 도구입니다. 프로젝트별로 정확한 패키지 매니저 버전을 지정하고 강제할 수 있습니다. 활성화되면 package.json의 packageManager 필드를 통해 프로젝트에서 사용할 패키지 매니저를 지정할 수 있습니다.

 

 

 

 

 

3.  해결 과정 📋

 

1. 로컬에서 패키지 매니저 충돌 해결하기

 

일단 Corepack을 비활성화 하였습니다.

# Corepack 비활성화 (관리자 권한 필요)
sudo corepack disable

 

그다음 package.json에 packageManager: ""을 삭제했습니다.

// 삭제 전
"packageManager": "yarn@1.22.19",

// 삭제 후
// packageManager 필드 완전 제거

 

전역적인 패키기 매니저 전환 없이 프로젝트 내에서만 pnpm을 사용하고 싶어서

 

 

2. devDependencies에 pnpm 추가: 

npm install --save-dev pnpm

 

3. npx를 통해 pnpm 실행:

"pnpm install" 직접 실행하면 시스템의 전역 환경에서 pnpm을 찾게 됩니다. 하지만 프로젝트 내에 로컬로 설치된 pnpm을 사용하려면 npx를 활용해야 합니다.

npx pnpm --version
npx pnpm install

 

4. 하지만 그전에 node_modules에 yarn의 기록이 남아있기 때문에

# node_modules 디렉토리 삭제
rm -rf node_modules

# pnpm 사용하여 의존성 다시 설치
npx pnpm install

 

이렇게 해주면 해당 프로젝트 내에서만 pnpm을 사용할 수 있고 배포 시에 pnpm install을 할 수 있게 됩니다!

 

 

🌎  여기서 npm과 npx 이해하기!

 이 두 도구는 비슷해 보이지만 가각 고유한 역할을 가지고 있습니다. 간단하게 말하자면, npm과 npx는 상호보완적인 도구입니다. npm으로 패키지를 관리하고, npx로 그 패키지들을 쉽게 실행할 수 있습니다. 특히 npx는 일회성 작업이나 CLI 도구를 사용할 때 전역 설치의 필요성을 줄여주어 개발 환경을 깔끔하게 유지하는 데 도움이 됩니다.

 

 

🌱 npm(Node Package Manager):

npm은 Node.js의 기본 패키지 관리자로, JavaScript 라이브러리 도구를 설치하고 관리하는데 사용됩니다.

 

주요 기능:

• 패키치 설치: npm install lodash
• 패키지 업데이트: npm update axios
• 패키지 제거: npm uninstall moment
• 설치된 패키지 목록 확인: npm list
• 새 프로젝트 초기화: npm init

npm은 패키지 의존성을 관리하고, 버전을 추적하며, package.json 파일을 통해 프로젝트 설정을 유지합니다.

 

 

🌱 npx(Node Package Execute):

npx는 npm 5.2.0 버전부터 함께 제공되는 도구로, 패키지를 실행하는데 특화 되어 있습니다.

 

주요 기능:

• 패키지 일회성 실행: 로컬에 설치하지 않고도 npm 패키지를 실행
• 로컬 도구 접근 간소화: 프로젝트에 설치된 도구를 전역 설치 없이 사용 가능

사용 예시: 코드 검사, 린팅(linting), 포맷팅, 보안 감사 등 개발 도구를 빠르고 쉽게 실행할 때 유용

• React 앱 생성: npx create-react-app my-app
• 코드 포맷팅: npx prettier --write .
• 정적 파일 서빙: npx serve -s build
• 가짜 REST API 서버: npx json-server --watch db.json
• TypeScript 파일 실행: npx ts-node script.ts
• 코드 품질 검사: npx eslint src/

 

 

 

 

 

 

4.  결론 ❤‍🔥

1. 프로젝트 패키지 매니저 일관성 유지: 하나의 프로젝트에서는 가능한 한 하나의 패키지 매니저만 사용하는 것이 좋습니다.
2. lock 파일의 중요성 이해: lock 파일은 의존성 정보를 정확히 기록하는 중요한 파일입니다.
   • package-lock.json: npm 사용
   • yarn.lock: yarn 사용
   • pnpm-lock.yaml: pnpm 사용
3. 배포 환경과 개발 환경 일치시키기: 로컬에서 사용하는 패키지 매니저와 배포 환경에서 사용하는 패키지 매니저를 일치시켜야 충돌을 방지할 수 있습니다.
4. Corepack 활용하기: 팀 프로젝트에서 Corepack을 활용하면 모든 팀원이 동일한 패키지 매니저와 버전을 사용하도록 강제할 수 있습니다.