Node.js 패키지 관리

이 페이지에서는 다음 태스크에 대해 설명합니다.

패키지와 패키지 버전 보기 및 삭제
태그 보기, 만들기, 업데이트 및 삭제

시작하기 전에

대상 저장소가 없으면 새 저장소를 만듭니다.
저장소에 대해 필요한 권한이 있는지 확인합니다.
npm 인증 구성
(선택사항) gcloud 명령어의 기본값을 구성합니다.
인증에 대해 npm 사용자 인증 정보 도우미를 사용하는 경우 npm을 사용해서 저장소에 연결하기 전 액세스 토큰을 가져옵니다.

필요한 역할

패키지를 관리하는 데 필요한 권한을 얻으려면 관리자에게 저장소에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

패키지, 패키지 파일, 태그 보기: Artifact Registry 리더(roles/artifactregistry.reader)
패키지 다운로드 또는 설치: Artifact Registry 리더(roles/artifactregistry.reader)
저장소에 패키지 추가: Artifact Registry 작성자(roles/artifactregistry.writer)
패키지 삭제: Artifact Registry 저장소 관리자(roles/artifactregistry.repoAdmin)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

액세스 토큰 가져오기

액세스 토큰은 60분 동안 유효합니다. 저장소와 상호작용하는 명령어를 실행하기 직전에 액세스 토큰을 생성합니다.

토큰을 받으려면 다음 옵션 중 하나를 사용합니다.

npx 명령어를 사용하여 액세스 토큰을 새로 고칩니다.
1. 공개 npm 레지스트리에 연결하기 위한 사용자 인증 정보가 사용자 npm 구성 파일 ~/.npmrc에 있는지 확인합니다.
2. Node.js 프로젝트 디렉터리에서 다음 명령어를 실행합니다.
```
npx google-artifactregistry-auth
```
  Artifact Registry 저장소가 전역 레지스트리로 설정되었고 패키지 범위가 지정되지 않은 경우, 대신 다음 명령어를 사용하여 명령어가 Artifact Registry 대신 공개 npm 레지스트리에서 사용자 인증 정보 도우미를 다운로드할 수 있게 하세요.
```
npm_config_registry=https://registry.npmjs.org npx google-artifactregistry-auth
```
프로젝트의 package.json 파일에 스크립트를 추가합니다.
```
"scripts": {
 "artifactregistry-login": "npx google-artifactregistry-auth"
}
```
Node.js 프로젝트 디렉터리에서 스크립트를 실행합니다.
```
npm run artifactregistry-login
```

Artifact Registry는 프로젝트 .npmrc 파일의 Artifact Registry 저장소 설정을 읽고 이를 사용하여 사용자 .npmrc 파일에 토큰 사용자 인증 정보를 추가합니다. 사용자 .npmrc 파일에 토큰을 저장하면 사용자 인증 정보가 소스 코드 및 소스 제어 시스템으로부터 격리됩니다.

패키지 추가

저장소 모드: 표준

패키지의 특정 버전을 한 번만 게시할 수 있습니다. 이는 게시된 패키지 버전 콘텐츠가 항상 동일하도록 보장하기 위한 npm 제한사항입니다. 따라서 다음을 수행할 수 없습니다.

저장소에 패키지 버전을 다시 게시하여 덮어쓰기
저장소에서 패키지 또는 해당 버전을 삭제한 다음 동일한 이름 및 버전 번호로 패키지 게시

패키지를 게시할 때 태그를 지정하지 않으면 npm이 latest 태그를 추가합니다. 특정 개발 단계에서 패키지 설치를 간소화하기 위해서는 beta 또는 dev와 같은 태그를 사용하여 패키지를 게시하는 것이 좋습니다.

Artifact Registry는 npm 패키지에 영숫자 소문자 패키지 이름을 적용합니다.

패키지를 추가하려면 다음 안내를 따르세요.

package.json의 패키지 이름에 저장소에 대해 구성된 범위가 포함되어 있는지 확인합니다. 다음 예시는 범위가 dev-repo인 패키지를 보여줍니다.
```
"name": "@dev-repo/my-package"
```
액세스 토큰으로 인증하기 위해 사용자 인증 정보 도우미를 사용하는 경우 새 토큰을 가져옵니다.
저장소에 패키지를 추가합니다. npm 또는 yarn 명령어를 사용할 수 있습니다.

패키지에 태그를 지정하려면 --tag 플래그를 포함하고 TAG를 사용하려는 태그로 바꿉니다. --tag 플래그를 포함하지 않으면 npm이 플래그를 자동으로 latest로 설정합니다.
```
npm publish --tag=TAG
```
```
yarn publish --tag TAG
```

패키지 및 버전 보기

저장소 모드: 표준, 원격, 가상

npm 또는 yarn으로 패키지 정보를 가져오려면 다음 안내를 따르세요.

액세스 토큰으로 인증하기 위해 사용자 인증 정보 도우미를 사용하는 경우 새 토큰을 가져옵니다.
적합한 명령어를 실행합니다.
```
npm view
```
```
yarn info
```

Google Cloud 콘솔 또는 gcloud를 사용하여 패키지 및 패키지 버전을 보려면 다음 안내를 따르세요.

콘솔

Google Cloud 콘솔에서 저장소 페이지를 엽니다.

저장소 페이지 열기
저장소 목록에서 적절한 저장소를 클릭합니다.

패키지 페이지에 저장소의 패키지가 나열됩니다.
패키지의 버전을 보려면 패키지를 클릭합니다.

gcloud

저장소의 패키지를 나열하려면 다음 명령어를 실행합니다.

gcloud artifacts packages list [--repository=REPOSITORY] [--location=LOCATION]

장소

REPOSITORY은 저장소 이름입니다. 기본 저장소를 구성한 경우 이 플래그를 생략하여 기본값을 사용할 수 있습니다.
LOCATION은리전 또는 멀티 리전위치입니다. 특정 위치의 저장소를 보려면 이 플래그를 사용합니다. 기본 위치를 구성한 경우 이 플래그를 생략하여 기본값을 사용할 수 있습니다.

패키지 버전을 보려면 다음 명령어를 실행합니다.

gcloud artifacts versions list --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION]

장소

PACKAGE는 패키지의 ID 또는 패키지의 정규화된 식별자입니다.
REPOSITORY은 저장소 이름입니다. 기본 저장소를 구성한 경우 이 플래그를 생략하여 기본값을 사용할 수 있습니다.
LOCATION은리전 또는 멀티 리전위치입니다. 특정 위치의 저장소를 보려면 이 플래그를 사용합니다. 기본 위치를 구성한 경우 이 플래그를 생략하여 기본값을 사용할 수 있습니다.

표준 및 원격 저장소의 패키지와 버전만 Google Cloud 콘솔이나 gcloud CLI에서 볼 수 있습니다.

원격 저장소의 경우 반환된 목록에 저장소에 캐시된 모든 직접 및 임시 종속 항목이 포함되어야 합니다.

파일 나열

저장소 모드: 표준, 원격

저장소의 파일, 지정된 패키지의 모든 버전 파일, 패키지의 특정 버전 파일을 나열할 수 있습니다.

다음 모든 명령어에 대해 --limit 플래그를 명령어에 추가하여 반환할 최대 파일 수를 설정할 수 있습니다.

기본값이 구성된 경우 기본 프로젝트, 저장소, 위치의 모든 파일을 나열하려면 다음 명령어를 실행합니다.

gcloud artifacts files list

지정된 프로젝트, 저장소, 위치의 파일을 나열하려면 다음을 실행합니다.

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION

특정 패키지의 모든 버전에 대한 파일을 나열하려면 다음을 실행합니다.

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE

특정 패키지 버전의 파일을 나열하려면 다음을 실행합니다.

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE \
    --version=VERSION

특정 태그의 파일을 나열하려면 다음을 실행합니다.

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE \
    --tag=TAG

다음 값을 바꿉니다.

LOCATION은 저장소의 리전 또는 멀티 리전 위치입니다.
PROJECT: Google Cloud 프로젝트 ID 프로젝트 ID에 콜론(`:`)이 포함되어 있으면 도메인 범위 프로젝트를 참조하세요.
REPOSITORY: 이미지가 저장된 저장소의 이름입니다.
PACKAGE: 패키지의 이름입니다.
VERSION: 패키지의 버전입니다.
TAG: 패키지와 연결된 태그입니다.

예시

다음 패키지 정보를 고려하세요.

프로젝트: my-project
저장소: my-repo
저장소 위치: us-west1
패키지: my-app

다음 명령어는 기본 프로젝트 내의 us-west1 위치에 있는 my-repo 저장소의 모든 파일을 나열합니다.

gcloud artifacts files list \
    --location=us-west1 \
    --repository=my-repo

다음 명령어는 패키지의 1.0 버전 파일을 나열합니다.

gcloud artifacts files list \
    --project=my-project \
    --location=us-west1 \
    --repository=my-repo \
    --package=my-app \
    --version=1.0

다음 명령어는 1.0-dev 태그가 있는 패키지 버전의 파일을 나열합니다.

gcloud artifacts files list \
    --project=my-project \
    --location=us-west1 \
    --repository=my-repo \
    --package=my-app \
    --tag=1.0-dev

패키지 태그 지정

저장소 모드: 표준

태그를 보고, 추가하고, 업데이트하고, 삭제할 수 있습니다. 태그를 사용하면 패키지의 시맨틱 버전을 관리하고 특정 개발 단계에서 패키지 설치를 간소화할 수 있습니다.

예를 들어 현재 출시 후보 빌드에 rc로 태그를 지정할 수 있습니다. 그러면 팀이 버전 지정자 대신 태그를 기반으로 올바른 버전을 설치할 수 있으며, 사용되지 않은 출시 전 버전을 게시 취소해도 출시 후보 패키지에 대한 종속 항목이 손상되지 않습니다.

태그 보기

패키지의 태그를 보려면 다음 안내를 따르세요.

콘솔

Google Cloud 콘솔에서 저장소 페이지를 엽니다.

저장소 페이지 열기
패키지를 클릭하여 버전 및 관련 태그를 확인합니다.
태그를 지정할 패키지 버전을 선택합니다.
선택한 버전 행에서 작업 더보기()를 클릭한 후 태그 수정을 클릭합니다.
입력란에 새 태그를 입력하고 저장을 클릭합니다.

gcloud

다음 명령어를 실행합니다.

gcloud artifacts tags list --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION]

장소

PACKAGE는 저장소의 패키지 이름입니다.
REPOSITORY는 저장소 이름입니다. 기본 저장소를 구성한 경우 이 플래그를 생략하여 기본값을 사용할 수 있습니다.
LOCATION은 리전 또는 멀티 리전 위치입니다. 특정 위치의 저장소를 보려면 이 플래그를 사용합니다. 기본 위치를 구성한 경우 이 플래그를 생략하여 기본값을 사용할 수 있습니다.

예를 들어 기본 위치의 my-repo 저장소에 있는 my-package 패키지의 태그를 보려면 다음 명령어를 실행합니다.

gcloud artifacts tags list --package=my-pkg --repository=my-repo

태그 생성

특정 버전의 패키지에 태그를 만들 수 있습니다.

저장소의 기존 이미지에 태그를 지정하려면 다음 안내를 따르세요.

콘솔

Google Cloud 콘솔에서 저장소 페이지를 엽니다.

저장소 페이지 열기
패키지의 버전을 보려면 패키지를 클릭합니다.
태그를 지정할 패키지 버전을 선택합니다.
선택한 버전 행에서 작업 더보기()를 클릭한 후 태그 수정을 클릭합니다.
입력란에 새 태그를 입력하고 저장을 클릭합니다.

gcloud

다음 명령어를 실행합니다.

gcloud artifacts tags create TAG --package=PACKAGE \
    version=VERSION [--location=LOCATION] [--repository=REPOSITORY]

장소

TAG는 패키지에 적용할 태그입니다.
PACKAGE는 저장소의 패키지 이름입니다.
VERSION은 태그를 지정할 패키지의 버전입니다.
LOCATION은 리전 또는 멀티 리전 위치입니다. 특정 위치의 저장소를 보려면 이 플래그를 사용합니다. 기본 위치를 구성한 경우 이 플래그를 생략하여 기본값을 사용할 수 있습니다.
REPOSITORY는 저장소 이름입니다. 기본 저장소를 구성한 경우 이 플래그를 생략하여 기본값을 사용할 수 있습니다.

예를 들어 기본 위치의 my-repo 저장소에 있는 my-package 패키지의 1.0.0 버전에 release-candidate 태그를 만들려면 다음 명령어를 실행합니다.

gcloud artifacts tags create release-candidate --version=1.0.0 \
    --package=my-pkg --repository=my-repo

태그 업데이트

패키지 버전과 연결된 태그를 변경할 수 있습니다.

기존 태그를 변경하는 방법은 다음과 같습니다.

콘솔

Google Cloud 콘솔에서 저장소 페이지를 엽니다.

저장소 페이지 열기
패키지의 버전을 보려면 패키지를 클릭합니다.
변경하려는 태그가 있는 패키지 버전을 선택합니다.
선택한 버전 행에서 작업 더보기()를 클릭한 후 태그 수정을 클릭합니다.
태그를 수정하고 저장을 클릭합니다.

gcloud

다음 명령어를 실행합니다.

gcloud artifacts tags update TAG --package=PACKAGE \
    version=VERSION [--location=LOCATION] [--repository=REPOSITORY]

장소

TAG는 패키지에 적용할 태그입니다.
PACKAGE는 저장소의 패키지 이름입니다.
VERSION은 태그를 지정할 패키지의 버전입니다.
LOCATION은 리전 또는 멀티 리전 위치입니다. 특정 위치의 저장소를 보려면 이 플래그를 사용합니다. 기본 위치를 구성한 경우 이 플래그를 생략하여 기본값을 사용할 수 있습니다.
REPOSITORY는 저장소 이름입니다. 기본 저장소를 구성한 경우 이 플래그를 생략하여 기본값을 사용할 수 있습니다.

예를 들어 기본 위치에 있는 저장소 my-repo에서 패키지 my-package 버전 1.0.0의 태그를 production으로 변경하려면 다음 명령어를 실행합니다.

gcloud artifacts tags update production --version=1.0.0 \
    --package=my-pkg --repository=my-repo

패키지 버전 태그 해제

패키지 버전에서 기존 태그를 삭제할 수 있습니다.

태그를 삭제하려면 다음 안내를 따르세요.

콘솔

Google Cloud 콘솔에서 저장소 페이지를 엽니다.

저장소 페이지 열기
이미지를 클릭하여 이미지의 버전을 확인합니다.
태그를 삭제할 이미지 버전을 선택합니다.
선택한 버전 행에서 작업 더보기()를 클릭한 후 태그 수정을 클릭합니다.
태그를 삭제하고 저장을 클릭합니다.

gcloud

다음 명령어를 실행합니다.

gcloud artifacts tags delete TAG --package=PACKAGE \
    [--location=<LOCATION] [--repository=REPOSITORY]

장소

TAG는 패키지에 적용할 태그입니다.
PACKAGE는 저장소의 패키지 이름입니다.
LOCATION은 리전 또는 멀티 리전 위치입니다. 특정 위치의 저장소를 보려면 이 플래그를 사용합니다. 기본 위치를 구성한 경우 이 플래그를 생략하여 기본값을 사용할 수 있습니다.
REPOSITORY는 저장소 이름입니다. 기본 저장소를 구성한 경우 이 플래그를 생략하여 기본값을 사용할 수 있습니다.

예를 들어 기본 위치의 my-repo 저장소에 있는 패키지 my-package에서 release-candidate 태그를 삭제하려면 다음 명령어를 실행합니다.

gcloud artifacts tags delete release-candidate --package=my-pkg \
    --repository=my-repo

패키지 설치

저장소 모드: 표준, 원격, 가상

Node.js 패키지 저장소에서 패키지를 설치하려면 다음 안내를 따르세요.

액세스 토큰으로 인증하기 위해 사용자 인증 정보 도우미를 사용하는 경우 새 토큰을 가져옵니다.
npm install 또는 yarn add 명령어를 사용합니다.
npm
latest 태그로 버전을 설치하려면 다음 안내를 따르세요.
```
npm install @SCOPE/PACKAGE
```
다른 태그로 버전을 설치하려면 다음 안내를 따르세요.
```
npm install @SCOPE/PACKAGE@TAG
```
특정 버전을 설치하려면 다음 안내를 따르세요.
```
npm install @SCOPE/PACKAGE@VERSION
```
yarn
latest 태그로 버전을 설치하려면 다음 안내를 따르세요.
```
yarn add @SCOPE/PACKAGE
```
다른 태그로 버전을 설치하려면 다음 안내를 따르세요.
```
yarn add @SCOPE/PACKAGE@TAG
```
특정 버전을 설치하려면 다음 안내를 따르세요.
```
yarn add @SCOPE/PACKAGE@VERSION
```
다음 값을 바꿉니다.
- SCOPE는 저장소와 연관된 범위입니다. Node.js 패키지 저장소가 범위로 구성되지 않았으면 명령어에서 @SCOPE/를 생략합니다.
- PACKAGE는 저장소의 패키지 이름입니다.
- TAG는 설치하려는 버전의 태그입니다.
- VERSION은 설치하려는 버전 번호입니다.

패키지를 package.json의 종속 항목을 지정할 때는 저장소의 범위를 포함해야 합니다. 다음 예시는 my-package라는 패키지의 @dev-repo 범위를 보여줍니다.

"dependencies": {
  "@dev-repo/my-package": ">=1.0.0"
}

표준 저장소의 경우 저장소에서 직접 패키지를 다운로드합니다.

원격 저장소의 경우 패키지와 해당 종속 항목의 캐시된 복사본을 다운로드합니다. 캐시된 복사본이 없으면 원격 저장소가 업스트림 소스에서 패키지를 다운로드하고 캐시한 후에 개발자에게 제공합니다. 저장소의 패키지 목록을 확인하여 원격 저장소가 업스트림 소스에서 패키지를 검색했는지 확인할 수 있습니다.

가상 저장소의 경우 Artifact Registry에서 요청된 패키지의 업스트림 저장소를 검색합니다.

캐시된 복사본이 없으면 업스트림 원격 저장소에서 요청된 패키지를 다운로드하고 캐시합니다. 가상 저장소는 요청된 패키지만 제공하고 저장하지 않습니다.
업스트림 저장소 2개 이상에서 사용할 수 있는 버전을 요청하면 Artifact Registry에서 가상 저장소에 구성된 우선순위 설정에 따라 사용할 업스트림 저장소를 선택합니다.

예를 들어 업스트림 저장소에 대해 다음 우선순위 설정을 사용하는 가상 저장소가 있다고 가정해보세요.

main-repo: 우선순위가 100으로 설정됩니다.
secondary-repo1: 우선순위가 80으로 설정됩니다.
secondary-repo2: 우선순위가 80으로 설정됩니다.
test-repo: 우선순위가 20으로 설정됩니다.

main-repo의 우선순위 값이 가장 높으므로 가상 저장소가 항상 이를 먼저 검색합니다.

secondary-repo1 및 secondary-repo2는 우선순위가 모두 80으로 설정됩니다. 요청된 패키지가 main-repo에 없으면 Artifact Registry가 그 다음으로 이 저장소를 검색합니다. 두 항목 모두 우선순위 값이 동일하므로, 두 항목 모두 버전을 사용할 수 있으면 Artifact Registry가 어느 저장소에서든 패키지를 제공하도록 선택할 수 있습니다.

test-repo는 우선순위 값이 가장 낮고 다른 업스트림 저장소에 없을 때만 저장된 아티팩트를 제공합니다.

패키지 삭제

저장소 모드: 표준, 원격

패키지 및 모든 해당 버전을 삭제하거나 특정 버전을 삭제할 수 있습니다.

패키지를 삭제하면 작업을 실행취소할 수 없습니다.
원격 저장소의 경우 패키지의 캐시된 복사본만 삭제됩니다. 업스트림 소스는 영향을 받지 않습니다. 캐시된 패키지를 삭제하면 다음에 저장소가 동일한 패키지 버전에 대한 요청을 받을 때 Artifact Registry가 해당 패키지를 다운로드하고 다시 캐시합니다.

패키지 버전이 게시된 후에는 버전을 삭제한 뒤라도 동일한 이름 및 버전 조합을 사용하여 패키지를 다시 게시할 수 없습니다. 이는 게시된 패키지 버전의 내용이 항상 동일하도록 보장하기 위한 npm 제한입니다.

사용자가 업데이트된 패키지 버전을 설치하도록 권장하려면 npm deprecate 명령어를 사용해서 이전 버전의 패키지를 지원 중단됨으로 표시합니다. 사용자가 지원 중단된 패키지를 설치하려고 시도하면 Artifact Registry가 지원 중단 경고를 반환합니다.

패키지 또는 패키지 버전을 삭제하기 전에 이에 대한 중요한 종속 항목에 대해 논의하거나 처리했는지 확인합니다.

패키지를 삭제하려면 다음 안내를 따르세요.

콘솔

Google Cloud 콘솔에서 저장소 페이지를 엽니다.

저장소 페이지 열기
저장소 목록에서 적절한 저장소를 클릭합니다.

패키지 페이지에 저장소의 패키지가 나열됩니다.
삭제할 위젯을 선택합니다.
삭제를 클릭합니다.
확인 대화상자에서 삭제를 클릭합니다.

gcloud

다음 명령어를 실행합니다.

gcloud artifacts packages delete PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] [--async]

장소

PACKAGE는 저장소의 패키지 이름입니다.
REPOSITORY는 저장소 이름입니다. 기본 저장소를 구성한 경우 이 플래그를 생략하여 기본값을 사용할 수 있습니다.
LOCATION은리전 또는 멀티 리전위치입니다. 특정 위치의 저장소를 보려면 이 플래그를 사용합니다. 기본 위치를 구성한 경우 이 플래그를 생략하여 기본값을 사용할 수 있습니다.
--async는 진행 중인 작업이 완료되기를 기다리지 않고 즉시 반환됩니다.

패키지 버전을 삭제하려면 다음 안내를 따르세요.

콘솔

Google Cloud 콘솔에서 저장소 페이지를 엽니다.

저장소 페이지 열기
저장소 목록에서 적절한 저장소를 클릭합니다.

패키지 페이지에 저장소의 패키지가 나열됩니다.
패키지의 버전을 보려면 패키지를 클릭합니다.
삭제할 버전을 선택합니다.
삭제를 클릭합니다.
확인 대화상자에서 삭제를 클릭합니다.

gcloud

다음 명령어를 실행합니다.

gcloud artifacts versions delete VERSION \
    --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] \
    [--async]

장소

PACKAGE는 저장소의 패키지 이름입니다.
REPOSITORY는 저장소 이름입니다. 기본 저장소를 구성한 경우 이 플래그를 생략하여 기본값을 사용할 수 있습니다.
LOCATION은리전 또는 멀티 리전위치입니다. 특정 위치의 저장소를 보려면 이 플래그를 사용합니다. 기본 위치를 구성한 경우 이 플래그를 생략하여 기본값을 사용할 수 있습니다.
--async는 진행 중인 작업이 완료되기를 기다리지 않고 즉시 반환합니다.

Node.js 패키지 관리

시작하기 전에

필요한 역할

액세스 토큰 가져오기

패키지 추가

패키지 및 버전 보기

콘솔

gcloud

파일 나열

예시

패키지 태그 지정

태그 보기

콘솔

gcloud

태그 생성

콘솔

gcloud

태그 업데이트

콘솔

gcloud

패키지 버전 태그 해제

콘솔

gcloud

패키지 설치

npm

yarn

패키지 삭제

콘솔

gcloud

콘솔

gcloud

다음 단계