스토어 & lockfile 설정

스토어 설정#

storeDir#

  • 기본값:
    • $PNPM_HOME 환경 변수가 설정되어 있으면 $PNPM_HOME/store
    • $XDG_DATA_HOME 환경 변수가 설정되어 있으면 $XDG_DATA_HOME/pnpm/store
    • Windows 환경: ~/AppData/Local/pnpm/store
    • macOS 환경: ~/Library/pnpm/store
    • Linux 환경: ~/.local/share/pnpm/store
  • 유형: path

모든 패키지가 저장되는 디스크 위치입니다.

저장소는 항상 설치가 발생하는 동일한 디스크에 있어야 합니다. 따라서 디스크당 하나의 저장소가 있도록 합니다. 현재 디스크에 홈 디렉토리가 있으면, 그 안에 저장소가 생성됩니다. 디스크에 홈이 없으면 파일 시스템의 루트에서 저장소가 생성됩니다. 예를 들어, /mnt에 마운트된 파일 시스템에서 설치가 진행되는 경우 스토어는 /mnt/.pnpm-store에 생성됩니다. Windows 시스템도 마찬가지입니다.

다른 디스크에서 저장소를 설정할 수 있지만, 이 경우 pnpm은 하드 링크 대신 저장소에서 패키지를 복사합니다. 하드 링크는 동일한 파일 시스템에서만 가능하기 때문입니다.

Important

서로 신뢰하는 사용자, 작업, 프로세스 사이에서만 pnpm 스토어를 공유하도록 설계되었습니다. 공유 storeDir를 구성하는 경우, 신뢰할 수 없는 사용자가 쓸 수 없도록 파일 시스템 권한으로 보호하세요. 스토어는 pnpm 신뢰 도메인의 일부입니다: 패키지가 스토어에서 하드 링크될 수 있으며, 스토어 인덱스(index.db)는 캐시된 파일을 검증하는 데 사용되는 해시를 기록합니다.

verifyStoreIntegrity#

  • 기본값: true
  • 타입: Boolean

기본적으로 스토어의 파일이 수정된 경우, 프로젝트의 node_modules에 링크하기 전에 이 파일의 내용을 확인합니다. verifyStoreIntegrity가 false로 설정되면, 설치 중에 콘텐츠 주소 지정 방식 스토어의 파일을 확인하지 않습니다.

이 설정은 실수로 인한 스토어 손상을 감지하는 데 도움이 됩니다. 스토어에 쓸 수 있는 공격자는 캐시된 패키지 콘텐츠와 이를 검증하는 데 사용되는 메타데이터를 모두 변경할 수 있으므로, 신뢰할 수 없는 사용자가 쓸 수 있는 스토어를 이 설정으로 안전하게 만들 수는 없습니다.

useRunningStoreServer#

위험

사용 중단된 기능

  • 기본값: false
  • 타입: Boolean

스토어 서버를 통한 설치만 허용합니다. 실행 중인 스토어 서버가 없으면 설치가 실패합니다.

strictStorePkgContentCheck#

  • 기본값: true
  • 타입: Boolean

일부 레지스트리에서는 정확히 동일한 콘텐츠를 다른 패키지 이름 및/또는 버전으로 게시할 수 있습니다. 이로 인해 스토어에 있는 패키지의 유효성 검사가 깨집니다. 스토어에서 이러한 패키지의 이름과 버전을 확인할 때 오류가 발생하지 않도록 하려면 strictStorePkgContentCheck 설정을 false로 지정할 수 있습니다.

frozenStore#

추가된 버전: v11.7.0

  • 기본값: false
  • 타입: Boolean

pnpm install이 읽기 전용 파일 시스템에 있는 패키지 스토어를 대상으로 실행될 수 있게 합니다 — 예를 들어 Nix 스토어, 읽기 전용 바인드 마운트 또는 OCI 이미지 레이어가 있습니다. 활성화하면 pnpm은 스토어의 SQLite index.db를 불변 모드로 열고(읽기 전용 디렉터리에서는 생성할 수 없는 WAL/-shm 사이드카 파일을 우회함) 스토어에 쓰기를 수행하는 모든 코드 경로를 억제합니다.

완전히 채워진 스토어를 대상으로 --offline 및 --frozen-lockfile과 함께 사용하세요:

pnpm install --frozen-store --offline --frozen-lockfile

스토어에는 라이프사이클 스크립트가 승인된(또는 패치가 적용된) 모든 패키지의 빌드 출력을 포함하여 설치에 필요한 모든 것이 이미 들어 있어야 합니다. 전역 가상 스토어에서는 이러한 패키지 디렉터리가 스토어 안에 있으므로, 필요한 빌드가 누락되면 설치가 ERR_PNPM_FROZEN_STORE_NEEDS_BUILD와 함께 즉시 실패합니다 — 먼저 해당 빌드로 스토어를 채우세요. 스토어에 콘텐츠 디렉터리가 아예 없으면, 설치는 이를 초기화하려 하지 않고 ERR_PNPM_FROZEN_STORE_INCOMPLETE와 함께 빠르게 실패합니다.

frozenStore는 --force 및 구성된 pnpr 서버와 호환되지 않는데, 둘 다 스토어에 쓰기 때문입니다. 사이드 이펙트 캐시도 기록되지 않습니다.

참고

읽기 전용 스토어 열기에는 Node.js >=22.15.0, >=23.11.0, 또는 >=24.0.0이 필요합니다. 이전 런타임에서는 --frozen-store가 ERR_PNPM_FROZEN_STORE_UNSUPPORTED_NODE와 함께 실패합니다.

Lockfile 설정#

lockfile#

  • 기본값: true
  • 타입: Boolean

false로 설정하면 pnpm은 pnpm-lock.yaml 파일을 읽거나 생성하지 않습니다.

preferFrozenLockfile#

  • 기본값: true
  • 타입: Boolean

true로 설정되어 있고 사용 가능한 pnpm-lock.yaml이 package.json 종속성 지시문을 충족하면 헤드리스 설치가 수행됩니다. 헤드리스 설치는 lockfile을 수정할 필요가 없기 때문에 모든 종속성 해석을 건너뜁니다.

lockfileIncludeTarballUrl#

  • 기본값: false
  • 타입: Boolean

pnpm-lock.yaml의 모든 항목에 패키지 tarball의 전체 URL을 추가합니다.

gitBranchLockfile#

  • 기본값: false
  • 타입: Boolean

true로 설정하면 병합 충돌을 완전히 방지하기 위해 설치 후 생성되는 lockfile 이름이 현재 브랜치 이름을 기반으로 지정됩니다. 예를 들어, 현재 브랜치 이름이 feature-foo라면 해당 lockfile 이름은 pnpm-lock.feature-foo.yaml이 되며, pnpm-lock.yaml은 사용되지 않습니다. 일반적으로 명령줄 인수 --merge-git-branch-lockfiles와 함께 사용하거나, mergeGitBranchLockfilesBranchPattern을 pnpm-workspace.yaml 파일에 설정하여 사용합니다.

mergeGitBranchLockfilesBranchPattern#

  • 기본값: null
  • 유형: Array or null

이 설정은 현재 브랜치 이름과 일치하는지 확인하여 모든 Git 브랜치 lockfile 파일을 병합할지 여부를 결정합니다. 기본적으로 --merge-git-branch-lockfiles 명령줄 매개변수를 수동으로 전달해야 합니다. 이 구성을 사용하면 이 프로세스가 자동으로 완료됩니다.

예를 들어:

mergeGitBranchLockfilesBranchPattern:
- main
- release*

!를 사용하여 패턴을 제외할 수도 있습니다.

peersSuffixMaxLength#

  • 기본값: 1000
  • 유형: number

피어 ID 접미사가 lockfile의 종속성 키에 추가될 때의 최대 길이입니다. 접미사가 이보다 길면 해시로 대체됩니다.