글로벌 가상 스토어

기본적으로 pnpm은 각 프로젝트의 node_modules 안에 .pnpm 디렉터리를 생성합니다 — 이것이 "가상 스토어"입니다. 이 디렉터리에는 콘텐츠 주소 지정 스토어에 있는 파일에 대한 하드 링크가 들어 있습니다. 모든 프로젝트는 이 가상 스토어의 자체 사본을 가집니다 — pnpm은 콘텐츠 주소 지정 스토어의 파일을 .pnpm 디렉터리 구조로 하드 링크합니다. 실제 파일 내용은 디스크에 한 번만 존재하지만, Node.js의 모듈 해석 알고리즘이 각 패키지에 맞는 종속성을 찾을 수 있도록 디렉터리 구조는 프로젝트마다 다시 생성됩니다.

글로벌 가상 스토어(enableGlobalVirtualStore: true)는 이를 변경합니다. 각 프로젝트가 자체 node_modules/.pnpm 디렉터리를 가지는 대신, pnpm은 하나의 공유 가상 스토어를 유지합니다(<store-path>/links/에 위치하며, <store-path>을 확인하려면 pnpm store path를 실행하세요). 각 프로젝트의 node_modules에는 이 공유 위치를 가리키는 심볼릭 링크만 들어 있습니다.

기본 동작과 글로벌 가상 스토어 비교#

기본값 (프로젝트별 가상 스토어)#

project-a/ └── node_modules/ ├── lodash → .pnpm/lodash@4.17.21/node_modules/lodash └── .pnpm/ └── lodash@4.17.21/ └── node_modules/ └── lodash/ ← hardlinks to content-addressable store project-b/ └── node_modules/ ├── lodash → .pnpm/lodash@4.17.21/node_modules/lodash └── .pnpm/ └── lodash@4.17.21/ └── node_modules/ └── lodash/ ← same hardlinks, duplicated directory structure

각 프로젝트는 하드 링크가 포함된 자체 .pnpm을 가집니다. 파일 내용은 디스크에서 중복되지 않지만(하드 링크는 inode를 공유합니다), 디렉터리 구조는 중복됩니다. 대규모 모노레포나 여러 개의 병렬 체크아웃에서는 pnpm install 중에 수천 개의 하드 링크를 생성하는 데 드는 시간이 누적됩니다.

글로벌 가상 스토어 사용 시#

project-a/ └── node_modules/ └── lodash → <global-store>/links/@/lodash/4.17.21/<hash>/node_modules/lodash project-b/ └── node_modules/ └── lodash → <global-store>/links/@/lodash/4.17.21/<hash>/node_modules/lodash ← same target

두 프로젝트 모두 글로벌 가상 스토어의 같은 위치로 직접 심볼릭 링크됩니다. 프로젝트별 .pnpm 디렉터리가 없습니다. 글로벌 가상 스토어 자체에는 콘텐츠 주소 지정 스토어에 대한 하드 링크가 들어 있지만, 이는 프로젝트마다가 아니라 종속성 그래프마다 한 번만 발생합니다(자세한 내용은 아래 참조).

패키지 식별 방식#

글로벌 가상 스토어에서 각 패키지 디렉터리의 이름은 해당 종속성 그래프의 해시로 지정됩니다. 동일한 전이 종속성 트리로 lodash@4.17.21을 사용하는 두 프로젝트는 정확히 같은 디렉터리를 가리킵니다. 종속성 트리가 다르면(예: 피어 종속성이 다른 경우) pnpm은 별도의 항목을 생성합니다. 이는 개념적으로 NixOS가 패키지를 관리하는 방식과 유사하게 종속성 그래프 해시를 사용합니다.

사용해야 하는 경우#

글로벌 가상 스토어는 디스크에 같은 프로젝트의 체크아웃이 여러 개 있을 때 가장 유용합니다. 예를 들어 멀티 에이전트 개발을 위한 git worktree를 사용하는 경우입니다. 이 경우 실제 패키지 콘텐츠가 모두 공유 스토어에 이미 존재하므로 각 worktree는 거의 비용 없이 node_modules를 얻습니다.

또한 어떤 프로젝트에서든 이미 설치된 패키지 버전은 즉시 사용할 수 있으므로, 같은 머신에 있는 서로 관련 없는 프로젝트 간의 설치 속도도 빨라집니다.

제한#

• CI 환경: CI에서는 일반적으로 캐시가 없으므로 활용할 수 있는 준비된 글로벌 스토어가 없습니다. 글로벌 가상 스토어는 일반적으로 CI에서는 유용하지 않습니다.
• 공유 신뢰 도메인: 글로벌 가상 스토어와 콘텐츠 주소 지정 스토어는 공유되는 쓰기 가능한 상태입니다. 서로 신뢰하는 프로젝트, 사용자, 작업에만 사용하고, 파일 시스템 권한으로 스토어 경로를 보호하세요.
• ESM 호이스팅: pnpm은 글로벌 가상 스토어에서 호이스팅된 종속성을 지원하기 위해 NODE_PATH 환경 변수를 사용합니다. 하지만 Node.js는 ESM import에 대해 NODE_PATH를 따르지 않습니다. ESM 종속성이 자체 package.json에 선언되지 않은 패키지를 import하려고 하면 해석에 실패합니다. packageExtensions 또는 @pnpm/plugin-esm-node-path 설정 종속성을 사용하여 이 문제를 해결할 수 있습니다.

글로벌 패키지#

버전 v11에서는 전역 설치(pnpm add -g)와 pnpm dlx가 기본적으로 글로벌 가상 스토어를 사용합니다. 격리된 설치와 새로운 바이너리 위치를 포함하여 v11에서 글로벌 패키지 관리가 작동하는 방식에 대한 전체 가이드는 Global Packages를 참고하세요.

환경설정#

모든 설정 세부 사항은 enableGlobalVirtualStore 설정 레퍼런스를 참고하세요.