종속성 해석 설정

overrides#

이 필드를 사용하면 피어 종속성을 포함하여 종속성 그래프의 모든 종속성을 재정의하도록 pnpm에 지시할 수 있습니다. 이는 모든 패키지가 종속성의 단일 버전을 사용하도록 강제하거나, 수정 사항을 백포트하거나, 종속성을 포크로 대체하거나, 사용하지 않는 종속성을 제거할 때 유용합니다.

참고로, 재정의 필드는 프로젝트의 루트에서만 설정할 수 있습니다.

overrides 필드의 예시입니다:

overrides:
  "foo": "^1.0.0"
  "quux": "npm:@myorg/quux@^1.0.0"
  "bar@^2.1.0": "3.0.0"
  "qar@1>zoo": "2"

패키지 선택자와 종속성 선택자를 ">"로 구분하여 재정의된 종속성이 속한 패키지를 지정할 수 있으며, 예를 들어 qar@1>zoo는 zoo 종속성을 qar@1에 속한 경우에만 재정의하고 다른 종속성에는 적용되지 않습니다.

재정의된 버전을 워크스페이스의 다른 곳에서 사용하는 버전과 동기화하려면, 카탈로그에 버전을 정의하고 catalog: 프로토콜로 참조하세요. 이렇게 하면 버전이 한 곳에서 관리되며 종속성과 재정의 양쪽에서 참조됩니다:

pnpm-workspace.yaml

catalog:
  foo: "^1.0.0"

overrides:
  foo: "catalog:"

catalog:<name>을 사용하여 이름이 지정된 카탈로그를 참조할 수도 있습니다. 자세한 내용은 카탈로그를 참조하세요.

특정 패키지를 사용할 때 해당 패키지의 종속성 중 하나가 필요하지 않다면, -를 사용하여 제거할 수 있습니다. 예를 들어, 패키지 foo@1.0.0이 사용하지 않는 기능을 위해 bar라는 큰 패키지를 필요로 한다면, 이를 제거하여 설치 시간을 줄일 수 있습니다:

overrides:
  "foo@1.0.0>bar": "-"

이 기능은 대부분의 선택적 패키지를 안전하게 건너뛸 수 있는 optionalDependencies에서 특히 유용합니다.

수렴 재정의#

추가된 버전: v11.13.0

빈 범위를 가진 선택자 — "pkg@" — 는 수렴 재정의입니다. 일치하는 모든 엣지를 무조건 다시 작성하는 일반 재정의와 달리, 수렴 재정의는 종속성 엣지의 버전이 해당 엣지가 선언한 범위를 충족하는 경우에만 그 엣지를 다시 작성합니다:

pnpm-workspace.yaml

overrides:
  "form-data@": 4.0.6

위 설정을 사용하면 form-data: "^4.0.5"를 선언한 종속성은 4.0.6으로 고정되며, ^3.0.0을 선언한 종속성은 자체 해석을 유지합니다. 이를 통해 호환되는 소비자가 그래프의 나머지 부분에 호환되지 않는 버전을 강제하지 않고도 현재 및 향후 추가될 모든 종속 항목에 대해 단일 버전으로 수렴할 수 있습니다.

규칙:

값은 정확한 버전이어야 합니다. 범위, dist-tag, 또는 - 제거는 ERR_PNPM_INVALID_CONVERGENCE_OVERRIDE와 함께 실패합니다. 카탈로그 항목이 정확한 버전으로 해석되는 한 catalog: 참조는 허용됩니다.
일반 semver 엣지만 참여합니다. workspace:, catalog:, npm:, dist-tag 또는 git/URL 지정자로 선언된 엣지는 의미 있는 "충족" 관계가 없으므로 그대로 유지됩니다.
수렴 재정의는 부모 선택자와 결합할 수 없습니다: "parent>pkg@"는 거부됩니다.
동일한 엣지에 대해서는 일반 재정의가 항상 수렴 재정의보다 우선합니다.

전체 해석 결과 선언된 모든 범위가 더 새로운 버전도 허용하는 것으로 확인되면, pnpm은 재정의가 오래되었다고 경고하고 대신 수렴할 버전을 알려줍니다.

참고

버전 v11.13.0 이전에는, 재정의 선택자의 빈 범위가 문서화되지 않았으며 일반(범위 지정되지 않은) 재정의처럼 동작했습니다.

피어 종속성 재정의#

재정의는 peerDependencies에도 적용됩니다. 동작은 재정의에 사용된 버전 지정자의 유형에 따라 달라집니다:

Semver 범위(예를 들어, ^1.0.0), workspace 및 catalog 프로토콜: 피어 종속성이 재정의되고 피어 종속성으로 유지됩니다.
범위가 아닌 지정자인 link: 또는 file: 프로토콜 등: 피어 종속성이 재정의되고 dependencies로 이동되는데, 이는 유효한 피어 종속성 범위가 아니기 때문입니다.
제거 (-): 피어 종속성이 완전히 제거됩니다.

예를 들어, react 피어 종속성을 react-dom에서 재정의하려면 다음과 같이 하세요:

pnpm-workspace.yaml

overrides:
  "react-dom>react": "18.1.0"

packageExtensions#

packageExtensions 필드는 기존 패키지 정의를 추가 정보로 확장하는 방법을 제공합니다. 예를 들어, react-redux에 react-dom이 peerDependencies로 있어야 하지만 없는 경우, react-redux를 packageExtensions로 패치할 수 있습니다:

packageExtensions:
  react-redux:
    peerDependencies:
      react-dom: "*"

packageExtensions의 키는 패키지 이름 또는 패키지 이름과 semver 범위이므로, 패키지의 일부 버전만 패치할 수 있습니다:

packageExtensions:
  react-redux@1:
    peerDependencies:
      react-dom: "*"

다음 필드는 packageExtensions를 사용하여 확장할 수 있습니다: dependencies, optionalDependencies, peerDependencies, 그리고 peerDependenciesMeta.

더 큰 예시:

packageExtensions:
  express@1:
    optionalDependencies:
      typescript: "2"
  fork-ts-checker-webpack-plugin:
    dependencies:
      "@babel/core": "1"
    peerDependencies:
      eslint: ">= 6"
    peerDependenciesMeta:
      eslint:
        optional: true

팁

Yarn과 함께 생태계의 손상된 패키지를 패치하기 위한 packageExtensions 데이터베이스를 유지 관리하고 있습니다. packageExtensions를 사용하는 경우, 업스트림에 PR을 보내고 확장을 @yarnpkg/extensions 데이터베이스에 기여하는 것을 고려해 주세요.

allowedDeprecatedVersions#

이 설정을 사용하면 특정 패키지의 사용 중단 경고를 끌 수 있습니다.

예시:

allowedDeprecatedVersions:
  express: "1"
  request: "*"

위 구성을 사용하면 pnpm은 모든 버전의 request와 express의 v1에 대한 사용 중단 경고를 출력하지 않습니다.

update#

추가된 버전: v11.16.0

이 섹션의 설정은 pnpm update 및 pnpm outdated 명령을 조정합니다.

update.ignoreDeps#

때로는 종속성을 업데이트할 수 없는 경우가 있습니다. 예를 들어 최신 버전의 종속성이 ESM을 사용하기 시작했지만 프로젝트가 아직 ESM을 사용하지 않을 수 있습니다. 번거롭게도 이러한 패키지는 항상 pnpm outdated 명령에 의해 출력되며, pnpm update --latest를 실행하면 업데이트됩니다. 하지만 업그레이드하지 않으려는 패키지를 ignoreDeps 필드에 나열할 수 있습니다:

update:
  ignoreDeps:
  - load-json-file

패턴도 지원되므로, 스코프의 모든 패키지를 무시할 수 있습니다: @babel/*.

update.changeset#

추가된 버전: v11.16.0

기본값: false
타입: Boolean

true이면 pnpm update는 워크스페이스 매니페스트를 업데이트한 후 변경 의도를 작성하며, patch 상승은 dependencies 또는 optionalDependencies가 업데이트로 변경된 모든 워크스페이스 패키지에 대해, major 상승은 peerDependencies가 변경된 경우에 선언합니다. --changeset을 전달하는 것과 같습니다; 한 번의 실행에서만 설정을 재정의하려면 --no-changeset을 전달하세요.

update.githubActions#

추가된 버전: v11.16.0

기본값: false
타입: Boolean

true이면 pnpm update와 pnpm outdated는 저장소의 워크플로 파일에서 참조하는 GitHub Actions도 확인합니다. --include-github-actions를 전달하는 것과 같습니다. GitHub Actions 업데이트를 참조하세요.

update.githubActionsServer#

추가된 버전: v11.17.0

기본값: GITHUB_SERVER_URL 환경 변수, 없으면 https://github.com
유형: URL

워크플로 파일에서 참조하는 GitHub Actions의 리포지토리를 호스팅하는 GitHub 서버의 기본 URL입니다(예를 들어, GitHub Enterprise Server). URL은 https:// 또는 http:// 프로토콜을 사용해야 합니다. 신뢰할 수 있는 네트워크의 신뢰할 수 있는 서버에만 http://를 사용하세요: 액션을 커밋 해시에 고정하는 데 사용되는 ref는 이 URL을 통해 가져오며, 암호화되지 않은 트래픽은 변조될 수 있습니다.

정보

버전 v11.16.0 이전에는, update.ignoreDeps의 이름이 updateConfig.ignoreDependencies였습니다. 사용 중단된 updateConfig 설정은 다음 메이저 버전까지 계속 동작합니다; 둘 다 설정된 경우, update 섹션이 우선하며 경고가 출력됩니다.

supportedArchitectures#

설치를 실행 중인 시스템의 아키텍처와 일치하지 않더라도, 선택적 종속성을 설치하고자 하는 아키텍처를 지정할 수 있습니다.

예를 들어, 다음 구성은 Windows x64용 선택적 종속성을 설치하도록 지정합니다:

supportedArchitectures:
  os:
  - win32
  cpu:
  - x64

이 구성은 Windows, macOS 및 현재 설치를 실행 중인 시스템의 아키텍처에 대한 선택적 종속성을 설치합니다. 이 구성에는 x64와 arm64 CPU용 아티팩트가 모두 포함됩니다:

supportedArchitectures:
  os:
  - win32
  - darwin
  - current
  cpu:
  - x64
  - arm64

또한 supportedArchitectures는 시스템의 libc 지정도 지원합니다.

ignoredOptionalDependencies#

선택적 종속성의 이름이 이 배열에 포함되어 있으면, 해당 종속성은 건너뜁니다. 예시:

ignoredOptionalDependencies:
- fsevents
- "@esbuild/*"

minimumReleaseAge#

버전 10.16.0에서 추가됨

기본값: 1440 (v11부터), 0 (v11 이전)
유형: number (minutes)

손상된 패키지를 설치할 위험을 줄이기 위해, 새로 게시된 버전의 설치를 지연시킬 수 있습니다. 대부분의 경우 악성 릴리스는 한 시간 이내에 발견되어 레지스트리에서 제거됩니다.

minimumReleaseAge는 버전이 게시된 후 pnpm이 이를 설치하기 전까지 경과해야 하는 최소 시간을 분 단위로 정의합니다. 이는 전이 종속성을 포함한 모든 종속성에 적용됩니다.

예를 들어, 다음 설정은 최소 하루 전에 릴리스된 패키지만 설치할 수 있도록 합니다:

minimumReleaseAge: 1440

minimumReleaseAgeExclude#

버전 10.16.0에서 추가됨

기본값: undefined
유형: string[]

minimumReleaseAge를 설정했지만 특정 종속성은 항상 최신 버전을 즉시 설치해야 하는 경우, 해당 종속성을 minimumReleaseAgeExclude에 나열할 수 있습니다. 제외는 패키지 이름 단위로 동작하며 해당 패키지의 모든 버전에 적용됩니다.

예시:

minimumReleaseAge: 1440
minimumReleaseAgeExclude:
- webpack
- react

이 경우 모든 종속성은 최소 하루가 지나야 하지만, webpack과 react는 예외로 릴리스되는 즉시 설치됩니다.

버전 10.17.0에서 추가됨

패턴을 사용할 수도 있습니다. 예를 들어, 조직의 모든 패키지를 허용하려면:

minimumReleaseAge: 1440
minimumReleaseAgeExclude:
- '@myorg/*'

버전 10.19.0에서 추가됨

특정 버전(또는 ||를 사용한 논리합으로 여러 특정 버전 목록)을 제외할 수도 있습니다. 이를 통해 성숙 기간 규칙에 대한 예외를 고정할 수 있습니다:

minimumReleaseAge: 1440
minimumReleaseAgeExclude:
- nx@21.6.5
- webpack@4.47.0 || 5.102.1

minimumReleaseAgeExcludePrune#

추가된 버전: v11.22.0

기본값: false
타입: Boolean

true로 설정하면 pnpm add, pnpm update, 그리고 pnpm remove는 minimumReleaseAgeExclude 항목 중 pnpm-workspace.yaml에 있으면서 새로 작성된 lockfile이 더 이상 해석하지 않는 항목을 정리합니다: 사라진 버전은 삭제되고(남은 버전이 없으면 항목이 제거됨), lockfile에 더 이상 없는 패키지의 항목도 제거됩니다. 이름 패턴(@myorg/*)은 항상 유지됩니다.

설치의 lockfile이 전체 워크스페이스를 포함하지 않는 경우(sharedWorkspaceLockfile: false) 정리를 건너뛰는데, 다른 프로젝트에서 여전히 필요한 항목이 오래된 것처럼 보일 수 있기 때문입니다.

minimumReleaseAgeIgnoreMissingTime#

추가된 버전: v11.0.0

기본값: true
타입: Boolean

true이면 pnpm은 minimumReleaseAge 검사를 건너뛰며, 이는 레지스트리 메타데이터에 time 필드가 포함되지 않은 패키지에 해당합니다(일부 비공개 레지스트리와 미러는 이 필드를 생략합니다). 이 경우 패키지를 설치하는 대신 해석을 실패시키려면 false로 설정하세요.

minimumReleaseAgeIgnoreMissingTime: false

minimumReleaseAgeStrict#

추가된 버전: v11.0.0

기본값: minimumReleaseAge가 명시적으로 구성된 경우 true, 그렇지 않으면 false
타입: Boolean

요청된 범위 내에서 minimumReleaseAge 제약 조건을 충족하는 종속성 버전이 없을 때 pnpm의 동작 방식을 제어합니다. false이면 pnpm은 minimumReleaseAge 제약 조건을 충족하지 않는 버전으로 대체하여 설치가 성공할 수 있도록 합니다. true이면 pnpm은 대신 해석을 실패시킵니다.

기본값은 minimumReleaseAge를 직접 구성했는지에 따라 달라집니다: 명시적으로 설정한 경우(pnpm-workspace.yaml, CLI 또는 환경 변수를 통해) 엄격 모드가 기본적으로 켜져 설정이 강제 적용됩니다. minimumReleaseAge의 내장 기본값(1440분)은 하위 호환성을 위해 엄격하지 않습니다.

minimumReleaseAgeStrict: true

trustPolicy#

버전 10.21.0에서 추가됨

기본값: off
유형: no-downgrade | off

no-downgrade로 설정하면, 패키지의 신뢰 수준이 이전 릴리스에 비해 낮아진 경우 pnpm이 실패합니다. 예를 들어, 패키지가 이전에는 신뢰할 수 있는 게시자에 의해 게시되었지만 현재는 출처 증명만 있거나 신뢰 증거가 없는 경우 설치가 실패합니다. 이는 손상되었을 가능성이 있는 버전의 설치를 방지하는 데 도움이 됩니다. 신뢰 검사는 semver가 아닌 게시 날짜만을 기준으로 합니다. 더 이전에 게시된 버전 중 하나라도 더 강력한 신뢰 증거를 가지고 있었다면 해당 패키지는 설치할 수 없습니다. 버전 v10.24.0부터는 프리릴리스가 아닌 버전을 설치할 때 신뢰 증거를 평가하면서 프리릴리스 버전을 무시하므로, 신뢰할 수 있는 프리릴리스가 신뢰 증거가 없는 안정 릴리스를 차단할 수 없습니다.

trustPolicyExclude#

버전 10.22.0에서 추가됨

기본값: []
유형: string[]

신뢰 정책 검사에서 제외할 패키지 선택자 목록입니다. 이를 통해 특정 패키지나 버전이 trustPolicy 요구 사항을 충족하지 않더라도 설치할 수 있습니다.

예시:

trustPolicy: no-downgrade trustPolicyExclude: - 'chokidar@4.0.3' - 'webpack@4.47.0 || 5.102.1' - '@babel/core@7.28.5'

trustPolicyIgnoreAfter#

버전 10.27.0에서 추가됨

기본값: undefined
유형: number (minutes)

지정한 분 수보다 더 오래전에 게시된 패키지에 대해 신뢰 정책 검사를 무시할 수 있습니다. 엄격한 신뢰 정책을 활성화할 때 유용한데, 오래된 버전의 패키지(서명이나 출처 증명을 포함한 게시 절차가 없을 수 있음)를 오래되었다는 이유로 안전하다고 가정하여 수동 제외 없이 설치할 수 있기 때문입니다.

trustLockfile#

추가된 버전: v11.3.0

기본값: false
타입: Boolean

값이 true이면 pnpm install은 로드된 lockfile의 모든 항목에 minimumReleaseAge와 trustPolicy를 다시 적용하는 공급망 검증 단계를 건너뜁니다. 설치 과정에서 lockfile을 이미 신뢰할 수 있는 것으로 취급합니다.

사실상 lockfile이 신뢰 기반의 일부인 환경에서 유용합니다 — 모든 커밋이 신뢰할 수 있는 작성자로부터 오는 비공개 소스 프로젝트가 그 예입니다. 오염된 lockfile(기여자가 CI가 강제하는 것보다 약한 정책하에서 작성한 것)이 통과될 수 있으므로, 외부 협력자가 lockfile을 편집할 수 있는 경우에는 항상 이 값을 false로 두세요.

대규모 워크스페이스에서는 검증 단계가 설치하는 동안 패키지별 레지스트리 메타데이터를 메모리에 유지합니다; 이를 비활성화하면 공급망 검사를 포기하는 대신 메모리 사용량이 줄어듭니다. 기본 frozenLockfile CI 워크플로를 사용하는 대부분의 프로젝트는 이 값을 설정할 필요가 없습니다.

blockExoticSubdeps#

버전 10.26.0에서 추가됨

기본값: true
타입: Boolean

값을 true로 설정하면 직접 종속성(루트 package.json에 나열된 종속성)만 비표준 소스(git 저장소나 직접 tarball URL 등)를 사용할 수 있습니다. 모든 전이 종속성은 구성된 레지스트리, 로컬 파일 경로, 워크스페이스 링크 또는 신뢰할 수 있는 GitHub 저장소(node, bun, deno)와 같은 신뢰할 수 있는 소스에서 해석되어야 합니다.

이 설정은 전이 종속성이 신뢰할 수 없는 위치에서 코드를 가져오는 것을 막아 종속성 공급망을 안전하게 지키는 데 도움이 됩니다.

비표준 소스에는 다음이 포함됩니다:

Git 저장소(git+ssh://...)
직접 tarball URL 링크(https://.../package.tgz)

registries#

추가된 버전: v11.0.0

기본값: undefined
유형: Record<string, RegistryDeclaration> 또는 Record<string, string>

프로젝트가 패키지를 설치하는 레지스트리를 선언합니다. 버전 v11.23.0부터는 각 레지스트리를 URL을 키로 하여 한 번만 선언하며, pnpm이 해당 레지스트리에 대해 아는 모든 정보가 그 항목에 담깁니다: 해당 레지스트리로 라우팅되는 scopes, 응답하는 bare-specifier prefix, 그리고 서버가 tarball URL을 구성하는 방식(serverType, supportsTimeField)입니다. 각 필드에 대한 전체 설명은 전용 레지스트리 페이지에 있습니다.

registries:
  https://npm.corp.example.com/:
    serverType: artifactory
    scopes: ["@my-org", "@internal"]
    prefix: work

스코프를 URL에 매핑하는 이전 형식도 여전히 허용됩니다. default 키는 주 레지스트리를 설정하며(registry라는 .npmrc 설정과 동일), 스코프 키는 특정 패키지 스코프에 대한 레지스트리를 구성합니다:

registries:
  default: https://registry.npmjs.org/
  "@my-org": https://private.example.com/
  "@internal": https://nexus.corp.com/

두 형식은 하나의 맵에서 혼용할 수 없습니다.

버전 v11.11.0부터는 이 설정을 전역 설정 파일 (config.yaml)에도 정의할 수 있으며, 이는 단일 저장소가 아니라 머신의 모든 프로젝트에 적용되어야 하는 레지스트리에 유용합니다. 그곳에서는 라우트(scopes 및 prefix)만 읽습니다; serverType과 supportsTimeField는 lockfile의 형태에 영향을 주므로 pnpm-workspace.yaml에서만 읽습니다 — 설정을 둘 수 있는 위치를 참고하세요.

namedRegistries#

추가된 버전: v11.1.0

기본값: undefined
유형: Record<string, string>

참고

버전 v11.23.0부터 사용 중단됨: 대신 prefix를 registries에 선언하세요 — 레지스트리 페이지를 참고하세요. namedRegistries는 여전히 읽히지만, registries가 선언하지 않은 접두사에 대해서만 읽힙니다; 두 설정이 모두 접두사를 선언하면 pnpm이 경고합니다. 아래의 별칭에 관한 모든 내용 — 내장 별칭, 예약된 이름, lockfile 키 — 은 prefix로 선언된 별칭에도 동일하게 적용됩니다.

패키지를 설치할 때 접두사로 사용할 수 있는 이름 있는 레지스트리 별칭을 vlt의 이름 있는 레지스트리 별칭 방식으로 정의합니다. 예를 들어, 다음과 같이 구성하면:

pnpm-workspace.yaml

namedRegistries:
  gh: https://npm.pkg.github.example.com/
  work: https://npm.work.example.com/

pnpm add work:@corp/lib@^2.0.0은 @corp/lib@^2.0.0을 https://npm.work.example.com/에서 해석합니다.

인증 정보는 기존의 URL별 .npmrc 항목(예를 들어, //npm.pkg.github.com/:_authToken=...)에서 가져오므로 별도의 인증 메커니즘이 필요하지 않습니다.

버전 v11.11.0부터는 이 설정을 전역 설정 파일 (config.yaml)에도 정의할 수 있으므로, work: 같은 별칭을 머신의 모든 프로젝트에서 공유할 수 있습니다.

내장 별칭#

다음 두 별칭은 별도 구성 없이 작동합니다:

별칭	레지스트리	참고
`gh:`	`https://npm.pkg.github.com/`	GitHub Packages npm 레지스트리입니다.
`npmjs:`	`https://registry.npmjs.org/`	공개 npm 레지스트리입니다. 버전 v11.20.0에서 추가되었습니다.

사용자가 namedRegistries에 정의한 항목은 이들 위에 병합되므로 둘 중 어느 것이든 재정의할 수 있습니다 — GitHub Enterprise Server 사용자는 gh를 자체 호스트로 지정하고, npmjs를 미러링하거나 프록시하는 조직은 npmjs를 미러로 지정해야 합니다:

pnpm-workspace.yaml

namedRegistries:
  gh: https://npm.pkg.github.example.com/
  npmjs: https://npm.internal.example.com/

npmjs:는 기본 registry가 내부 프록시 등 다른 곳을 가리키는 경우에도 종속성을 공개 레지스트리에 고정합니다:

package.json

{
  "dependencies": {
    "left-pad": "npmjs:^1.3.0"
  }
}

npm: 접두사로는 이렇게 할 수 없습니다 — 이는 별칭 프로토콜 (npm:<name>@<range>)이며 registry가 가리키는 곳을 통해 해석됩니다.

내장 URL은 pnpm이 패키지를 검증할 때 lockfile에 기록된 tarball URL과 대조하는 접두사이기도 합니다. 자체 프록시로 npmjs를 중계하면서 별칭을 재정의하지 않으면, tarball URL이 registry.npmjs.org에 있는 항목은 미러가 아닌 공개 레지스트리를 기준으로 검증됩니다. 이는 이러한 URL을 기록한 lockfile에만 영향을 주며 — 구성된 레지스트리의 표준 URL은 lockfile에서 생략됩니다 — tarball URL, minimumReleaseAge 또는 trustPolicy 검사가 실행될 때만 해당됩니다.

예약된 별칭 이름#

버전 v11.20.0부터는 예약된 종속성 지정자 접두사(file, link, workspace, runtime, npm, jsr, git, github, gitlab, bitbucket, catalog, custom, http, https, ssh)를 가리는 별칭은 ERR_PNPM_RESERVED_NAMED_REGISTRY_NAME 오류와 함께 거부됩니다. 이전에는 이러한 별칭이 해당 리졸버에 의해 조용히 가려졌습니다. 또한 별칭은 문자로 시작해야 하며 문자, 숫자, ., _, -만 포함할 수 있습니다.

이름 있는 레지스트리의 lockfile 기록#

버전 v11.20.0부터는 이름 있는 레지스트리에서 해석된 패키지가 pnpm-lock.yaml에 레지스트리로 한정된 키인 <name>@<registryName>:<version> 형식으로 기록됩니다:

pnpm-lock.yaml

packages:
  foo@work:1.0.0:
    resolution: {integrity: sha512-...}

버전 v11.20.0 이전에는 패키지의 키가 name@version뿐이었기 때문에, 두 레지스트리에서 제공되는 같은 이름과 버전이 하나의 항목으로 합쳐졌고, 먼저 해석된 쪽이 모든 사용자가 받는 tarball을 결정했습니다. 이는 패키지 대체 위험입니다: 비공개 레지스트리에서 받을 것으로 예상한 패키지가 같은 이름과 버전을 게시한 다른 레지스트리에서 설치될 수 있으며, lockfile에는 이를 드러내는 정보가 전혀 없습니다. 레지스트리로 한정된 키는 각 레지스트리에 고유한 항목을 부여하고 종속성이 어느 레지스트리에서 왔는지 고정합니다.

이때 lockfile 형식 버전은 변경되지 않으며, 한정된 키는 이름 있는 레지스트리에서 해석된 패키지에만 나타납니다 — 내장 gh: 및 npmjs: 별칭도 포함되며, 이들은 namedRegistries 항목이 필요 없습니다. 별칭을 통해 아무것도 설치하지 않는 프로젝트에서는 차이가 없으며, 이전 버전의 pnpm도 계속 파일을 읽을 수 있습니다.

주의

별칭을 통해 설치된 종속성이 있다면, v11.20.0 이상에서 처음 수행하는 non-frozen 설치가 해당 항목의 키를 다시 지정하며, 이는 lockfile diff로 나타납니다. 이를 커밋하세요 — 그 diff가 바로 적용되는 수정 사항입니다. 검토도 하세요: 예상하지 못한 레지스트리로 옮겨진 항목은 조사해 볼 가치가 있습니다.

프로젝트에 참여하는 모든 사람이 먼저 v11.20.0 이상으로 이전하도록 하세요. 이전 버전의 pnpm도 키가 다시 지정된 lockfile을 문제없이 읽고 frozen 설치에도 영향이 없지만, 레지스트리로 한정된 키를 직접 생성하지는 않습니다: lockfile을 업데이트하는 모든 설치는 해당 항목을 이전 형식으로 되돌려 쓰고, 다음에 최신 pnpm으로 설치하면 다시 한정됩니다. 그러면 lockfile이 두 형식 사이를 오가게 되며, 이전 형식인 동안에는 프로젝트가 다시 위험에 노출됩니다. 의도적으로 lockfile 형식 버전을 변경하지 않았기 때문에 pnpm은 이를 감지하여 경고할 수 없습니다.

이전 동작을 유지하는 설정은 없습니다 — 이전 형식 자체가 취약점입니다.

내장되지 않은 별칭 중 lockfile이 참조하는 모든 별칭은 계속 선언되어 있어야 합니다 — prefix를 registries에 선언하거나 namedRegistries를 통해서입니다. 별칭이 사라진 항목을 읽으면 ERR_PNPM_MISSING_NAMED_REGISTRY 오류로 실패하며 기본 레지스트리로 대체되지 않는데, 대체하면 다른 패키지를 가져오게 되기 때문입니다. 별칭의 이름을 바꾸면 해당 별칭을 사용하던 패키지가 다시 해석됩니다.

이름 있는 레지스트리 패키지의 경우, 표준 레지스트리 레이아웃을 따르는 tarball URL은 더 이상 lockfile에 기록되지 않습니다; 필요할 때 별칭에 선언된 URL로부터 다시 계산됩니다.