pnpm 설치와 패키지·잠금 파일 관리

01현재 설치 조건과 프로젝트 버전

2026년 11월 8일 공식 설치 문서는 pnpm 12를 현재 계열로 안내합니다. pnpm 12 자체는 네이티브 실행 파일이며, npm 패키지로 설치할 때는 Node.js 18 이상이 필요합니다. npx get-pnpm 설치 도우미는 Node.js 22.13 이상을 요구합니다. 설치 방법의 조건과 프로젝트 코드의 Node.js 요구를 나눠 읽으세요.

기존 저장소에서는 package.json의 packageManager, CI 설정·프로젝트 문서를 먼저 확인합니다. 최신 전역 버전보다 프로젝트가 고정한 버전을 우선 대조하세요. 이 글에서 기존 프로젝트의 관리자를 실제로 전환하지는 않았습니다.

02Windows 설치와 명령 확인

공식 문서는 Windows에서 npm 설치 경로를 권장합니다. 새로 도구를 준비하는 경우의 명령 예시는 다음과 같습니다.

node --version
npm install -g pnpm@latest
pnpm --version

이는 설치 예시이며 이번 검수에서 실행하지 않았습니다. 기존 프로젝트가 다른 버전을 고정했다면 해당 버전을 준비해야 합니다. 명령이 엉뚱한 버전을 가리키면 where.exe pnpm.*로 경로를 확인하고 여러 설치가 겹쳤는지 살펴보세요. 보안 프로그램 제외 설정은 첫 해결책으로 적용하지 않습니다.

03설치·추가·실행의 차이

스크립트는 프로젝트에 실제로 정의돼 있어야 합니다. test 명령이 있다는 이유만으로 충분한 검사가 구현돼 있다고 볼 수 없습니다. 패키지 추가 후에는 package.json과 잠금 파일의 변경을 함께 검토하세요.

04잠금 파일과 frozen 옵션

package.json은 요구 버전 범위를, pnpm-lock.yaml은 해석된 의존성을 기록합니다. 잠금 파일만 있다고 패키지가 이미 설치된 것은 아닙니다. 준비된 프로젝트에서 pnpm install --frozen-lockfile을 쓰면 잠금 파일을 갱신하지 않고, 선언과 맞지 않을 때 오류를 확인할 수 있습니다.

공식 문서는 CI에서 잠금이 있는데 갱신이 필요한 경우 설치가 실패한다고 안내합니다. 오류를 없애려고 잠금을 바로 삭제하거나 frozen을 무조건 해제하지 말고, 의존성 변경이 의도된 것인지 먼저 확인하세요.

05자체 사례: add와 전역 설치가 섞였을 때

가상의 이용자가 pnpm add -g 도구로 설치한 뒤 프로젝트 의존성에 기록됐다고 생각한다고 가정합니다. 전역 CLI 설치와 프로젝트 패키지 추가는 다른 범위입니다. 이 사례에서는 package.json의 실제 의존성과 실행할 스크립트를 확인하는 것이 결과입니다.

기존 OpenCode·OpenClaw 글의 pnpm 언급은 해당 CLI를 설치하는 선택지이며 이 글의 프로젝트 패키지 관리와 다릅니다. 실제 pnpm 설치·패키지 다운로드·잠금 생성·스크립트 실행·관리자 전환은 수행하지 않았습니다. 공식 명령 의미와 자체 범위 구분 사례를 확인했습니다.

06목적별 가이드

07참고 자료

• pnpm 현재 설치 조건
• pnpm install과 frozen-lockfile
• pnpm add와 의존성 종류