인증 및 레지스트리 설정 (.npmrc)

이 페이지의 설정은 .npmrc 파일로 구성해야 합니다. pnpm은 게시 시 내부적으로 npm CLI를 사용하므로, 이 설정들은 npm이 읽을 수 있는 형식이어야 합니다.

.npmrc 파일이 로드되는 방식에 대한 자세한 내용은 pnpm config 명령을 참조하세요.

pnpm-workspace.yaml에서 구성할 수 있는 설정은 설정 (pnpm-workspace.yaml)을 참조하세요.

환경 변수#

.npmrc 파일의 값은 ${NAME} 구문을 사용해 환경 변수를 참조할 수 있습니다.

버전 v10.34.2부터는 프로젝트 및 워크스페이스 .npmrc 파일(저장소와 함께 체크아웃된 파일)에서 다음 설정에 대해 환경 변수가 확장되지 않습니다:

레지스트리 및 프록시 URL (registry, @scope:registry, proxy, https-proxy, http-proxy);
URL 범위 키(//로 시작하는 키);
자격 증명 값(_authToken, _auth, _password, username, tokenHelper, cert, key).

이러한 위치 중 하나에 ${...} 자리 표시자가 포함된 설정은 무시되며, pnpm은 경고를 출력합니다. 저장소에서 제어하는 .npmrc 파일은 환경 변수를 pnpm이 요청을 보내는 URL이나 해당 요청에 첨부되는 자격 증명으로 확장할 수 없어야 합니다 — 그렇지 않으면 악의적인 저장소가 설치 중에 사용자 환경의 비밀 값(예: CI 토큰)을 공격자가 제어하는 레지스트리로 유출할 수 있습니다 (GHSA-3qhv-2rgh-x77r).

프로젝트가 //registry.npmjs.org/:_authToken=${NPM_TOKEN}과 같은 줄이 포함된 커밋된 .npmrc에 의존했다면, 대신 토큰을 신뢰할 수 있는 위치로 옮기세요:

설치하기 전에 토큰을 전역 구성 파일에 기록하세요(예: CI 단계에서):
```
pnpm config set //registry.npmjs.org/:_authToken "$NPM_TOKEN"
```
pnpm config set은 기본적으로 프로젝트의 .npmrc가 아니라 전역 구성 파일에 기록하므로 토큰이 저장소에 남지 않습니다.
또는 ${NPM_TOKEN} 플레이스홀더 줄을 유지하되, 저장소가 아닌 사용자 수준의 ~/.npmrc에 두세요 — 그곳에서는 환경 변수가 여전히 확장됩니다.
또는 .npmrc 항목 없이 환경 변수를 통해 직접 값을 설정할 수도 있습니다:
```
npm_config_//registry.npmjs.org/:_authToken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```
GitHub Actions에서 registry-url 입력과 함께 actions/setup-node를 사용하면 인증 설정이 사용자 수준 .npmrc(pnpm이 따르는 NPM_CONFIG_USERCONFIG 환경 변수가 참조)에 기록되므로, NODE_AUTH_TOKEN 환경 변수를 통한 인증이 계속 작동합니다.
각 CI 파이프라인을 쉽게 수정할 수 없는 경우, CI 환경(예: 조직 또는 워크스페이스 수준)에서 단일 환경 변수를 설정하여 프로젝트 .npmrc를 신뢰할 수 있는 것으로 선언할 수 있습니다:
```
NPM_CONFIG_USERCONFIG=.npmrc
```
이렇게 하면 pnpm이 프로젝트의 .npmrc를 사용자 수준 구성 파일로 읽으며(상대 경로는 작업 디렉터리를 기준으로 해석됩니다), 그 안의 환경 변수는 이전처럼 확장됩니다. 신뢰 선언은 저장소가 아닌 환경에서 오므로, 악의적인 저장소가 이를 대신 설정할 수 없습니다.

위험

신뢰할 수 있는 저장소만 빌드하는 환경에서만 사용하세요. 이는 체크아웃된 저장소에 대해 tokenHelper를 사용자 수준 구성에서만 설정할 수 있다는 제한을 포함하여 이 보호 기능을 완전히 비활성화합니다.

프로젝트 또는 워크스페이스 .npmrc의 레지스트리 및 프록시 URL(registry, @scope:registry, proxy, https-proxy, http-proxy)에도 같은 규칙이 적용됩니다. 환경 변수를 사용해 레지스트리 URL을 만들었다면 설정을 신뢰할 수 있는 출처로 옮기세요 — 사용자 수준의 ~/.npmrc, 전역 구성(pnpm config set "<key>" <value>), CLI 옵션 또는 환경 변수입니다. URL이 비밀 정보가 아니라면 ${...} 자리 표시자만 무시되므로, 해석된 값을 프로젝트 .npmrc에 직접 작성할 수도 있습니다.

레지스트리 설정#

레지스트리#

기본값: https://registry.npmjs.org/
유형: url

npm 패키지 레지스트리의 기본 URL (후행 슬래시 포함).

@jsr:registry#

버전 10.9.0에서 추가됨

기본값: https://npm.jsr.io/
유형: url

JSR 패키지 레지스트리의 기본 URL입니다.

<scope>:registry#

지정된 범위의 패키지에 사용해야 하는 npm 레지스트리입니다. 예를 들어 @babel:registry=https://example.com/packages/npm/를 설정하면 pnpm add @babel/core 또는 @babel 스코프의 패키지를 사용할 때 기본 레지스트리 대신 https://example.com/packages/npm에서 패키지를 가져오도록 강제됩니다.

인증 설정#

<URL>:_authToken#

지정된 레지스트리에 액세스할 때 사용할 인증 bearer 토큰을 정의합니다. 예시:

//registry.npmjs.org/:_authToken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

환경 변수를 사용할 수도 있습니다. 예시:

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

버전 v10.34.2부터는 환경 변수가 신뢰할 수 있는 위치(사용자 ~/.npmrc, 전역 구성, CLI 옵션, npm_config_* 환경 변수)에서만 확장되며, 프로젝트 또는 워크스페이스 .npmrc에서는 확장되지 않습니다. 자세한 내용은 환경 변수를 참조하세요.

또는 .npmrc를 전혀 변경하지 않고 환경 변수를 직접 사용할 수도 있습니다:

npm_config_//registry.npmjs.org/:_authToken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

<URL>:tokenHelper#

토큰 헬퍼는 인증 토큰을 출력하는 실행 파일입니다. 이것은 authToken이 상수 값이 아니라 정기적으로 새로 고쳐지는 상황에서 사용할 수 있습니다. 스크립트나 다른 도구가 기존 리프레시 토큰을 사용하여 새 액세스 토큰을 얻을 수 있습니다.

헬퍼에 대한 경로 구성은 인수가 없는 절대 경로여야 합니다. 보안을 위해 이 값은 사용자 .npmrc에서만 설정할 수 있습니다. 그렇지 않으면 프로젝트가 프로젝트의 로컬 .npmrc에 값을 넣어 임의의 실행 파일을 실행할 수 있습니다.

기본 레지스트리에 대한 토큰 헬퍼 설정:

tokenHelper=/home/ivan/token-generator

지정된 레지스트리에 대한 토큰 헬퍼 설정:

//registry.corp.com:tokenHelper=/home/ivan/token-generator

프록시 설정#

https-proxy#

기본값: null
유형: url

외부로 나가는 HTTPS 요청에 사용할 프록시입니다. HTTPS_PROXY, https_proxy, HTTP_PROXY 또는 http_proxy 환경 변수가 설정된 경우 해당 값이 대신 사용됩니다.

프록시 URL에 사용자 이름과 비밀번호가 포함된 경우 반드시 URL 인코딩하세요. 예를 들어:

https-proxy=https://use%21r:pas%2As@my.proxy:1234/foo

사용자 이름과 비밀번호 사이의 콜론(:)은 인코딩하지 마세요.

http-proxy#

proxy#

기본값: null
유형: url

나가는 http 요청에 사용할 프록시입니다. HTTP_PROXY 또는 http_proxy 환경 변수가 설정되어 있으면 내부적으로 사용하는 request 라이브러리가 프록시 설정을 따릅니다.

local-address#

기본값: undefined
유형: IP Address

로컬 인터페이스의 IP 주소로, npm 레지스트리에 연결할 때 사용됩니다.

maxsockets#

기본값: networkConcurrency x 3
유형: Number

최대 연결 수는 origin(프로토콜/호스트/포트 조합)당 사용할 수 있는 연결의 최대 개수입니다.

noproxy#

기본값: null
유형: String

프록시를 사용하지 않아야 하는 도메인 확장자를 쉼표로 구분한 문자열입니다.

SSL 설정#

strict-ssl#

기본값: true
유형: Boolean

HTTPS를 통해 레지스트리에 요청할 때 SSL 키 검증을 수행할지 여부입니다.

함께 ca 옵션을 참조하세요.

인증서 설정#

ca#

기본값: npm CA 인증서
유형: String, Array 또는 null

레지스트리에 대한 SSL 연결을 위해 신뢰되는 인증 기관 서명 인증서입니다. 값은 PEM 형식("Base-64 encoded X.509 (.CER)"이라고도 함)이어야 합니다. 예시:

ca="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"

알려진 등록 기관만 허용하려면 null로 설정하고, 특정 서명 기관만 신뢰하려면 해당 CA 인증서로 설정하세요.

인증서 배열을 지정하여 여러 CA를 신뢰할 수 있습니다:

ca[]="..."
ca[]="..."

함께 strict-ssl 설정을 참조하세요.

cafile#

기본값: null
유형: path

하나 이상의 인증 기관 서명 인증서가 포함된 파일의 경로입니다. 설정 ca와 비슷하지만 여러 CA를 허용하며, CA 정보를 CLI로 지정하는 대신 파일에 저장할 수도 있습니다.

<URL>:cafile#

지정한 레지스트리에 접근할 때 사용할 인증 기관 파일의 경로를 정의합니다. 예시:

//registry.npmjs.org/:cafile=ca-cert.pem

<URL>:ca#

버전 10.25.0에서 추가됨

지정한 레지스트리에 대한 인라인 인증 기관 인증서를 정의합니다. 값은 전역 ca 설정처럼 PEM 인코딩이어야 하지만, 일치하는 레지스트리 URL에만 적용됩니다.

//registry.example.com/:ca=-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----

cert#

기본값: null
유형: String

레지스트리에 접근할 때 전달할 클라이언트 인증서입니다. 값은 PEM 형식("Base-64 encoded X.509 (.CER)"이라고도 함)이어야 합니다. 예시:

cert="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"

인증서 파일의 경로가 아닙니다.

<URL>:cert#

버전 10.25.0에서 추가됨

지정한 레지스트리에 접근할 때 사용할 인라인 클라이언트 인증서를 정의합니다. 예시:

//registry.example.com/:cert=-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----

<URL>:certfile#

지정한 레지스트리에 접근할 때 사용할 인증서 파일의 경로를 정의합니다. 예시:

//registry.npmjs.org/:certfile=server-cert.pem

key#

기본값: null
유형: String

레지스트리에 접근할 때 전달할 클라이언트 키입니다. 값은 PEM 형식("Base-64 encoded X.509 (.CER)"이라고도 함)이어야 합니다. 예시:

key="-----BEGIN PRIVATE KEY-----\nXXXX\nXXXX\n-----END PRIVATE KEY-----"

키 파일의 경로가 아닙니다. 키를 인라인으로 넣는 대신 파일 시스템을 참조해야 한다면 <URL>:keyfile을 사용하세요.

이 설정에는 민감한 정보가 포함되어 있습니다. 저장소에 커밋되는 로컬 .npmrc 파일에는 기록하지 마세요.

<URL>:key#

버전 10.25.0에서 추가됨

지정한 레지스트리 URL에 대한 인라인 클라이언트 키를 정의합니다.

//registry.example.com/:key=-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----

<URL>:keyfile#

지정한 레지스트리에 접근할 때 사용할 클라이언트 키 파일의 경로를 정의합니다. 예시:

//registry.npmjs.org/:keyfile=server-key.pem