管理 Node.js 套件

本頁面說明如何執行下列工作：

查看及刪除套件和套件版本
查看、建立、更新及刪除標記

事前準備

如果目標存放區不存在，請建立新的存放區。
確認您具備存放區的必要權限。
設定 npm 的驗證機制。
(選用) 設定 gcloud 指令的預設值。
如果您使用 npm 憑證輔助程式進行驗證，請先取得存取權杖，再透過 npm 連線至存放區。

必要的角色

如要取得管理套件所需的權限，請要求管理員在存放區中授予下列 IAM 角色：

查看套件、套件中的檔案和標記： Artifact Registry Reader (roles/artifactregistry.reader)
下載或安裝套件： Artifact Registry 讀取者 (roles/artifactregistry.reader)
將套件新增至存放區： Artifact Registry Writer (roles/artifactregistry.writer)
刪除套件： Artifact Registry 存放區管理員 (roles/artifactregistry.repoAdmin)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

取得存取權杖

存取權杖的效期為 60 分鐘。請在執行與存放區互動的指令前不久，產生存取權杖。

如要取得權杖，請使用下列其中一個選項：

使用 npx 指令更新存取權杖。
1. 請確認使用者 npm 設定檔 ~/.npmrc 中有連線至公開 npm 登錄檔的憑證。
2. 在 Node.js 專案目錄中執行下列指令。
```
npx google-artifactregistry-auth
```
  如果 Artifact Registry 存放區設為全域登錄檔，且套件未設為範圍，請改用下列指令，讓指令從公開 npm 登錄檔下載憑證輔助程式，而非 Artifact Registry 存放區。
```
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 控制台中開啟「Repositories」頁面。

開啟「存放區」頁面
在存放區清單中，按一下適當的存放區。

「Packages」頁面會列出存放區中的套件。
按一下套件即可查看套件版本。

gcloud

如要列出存放區中的套件，請執行下列指令：

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

更改下列內容：

REPOSITORY 是存放區的名稱。如果您已設定預設存放區，可以省略此標記來使用預設值。
LOCATION 是存放區的地區或多地區位置。如果您已設定預設位置，則可以省略此標記，以便使用預設值。

如要查看套件的版本，請執行下列指令：

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

更改下列內容：

PACKAGE 是套件的 ID 或套件的完整 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

標記套件

存放區模式：標準

You can view, add, update, and delete tags. Tags can help you manage semantic versions of your packages and streamline installation of packages at a specific stage of development.

For example, you can tag the current release candidate build with rc. Your team can then install the correct version based on the tag instead of a version specifier, and unpublishing unused pre-release versions won't break your dependencies on the release candidate package.

Viewing tags

To view tags for a package:

Console

Open the Repositories page in the Google Cloud console.

開啟「存放區」頁面
Click the package to view versions and the associated tags.
Select the package version to tag.
In the row of the selected version, click More actions (), and then click Edit tags.
Type new tags into the field and then click SAVE.

gcloud

Run the command:

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

Where

PACKAGE is the name of the package in the repository.
REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.
LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.

For example, to view tags for the package my-package in the repository my-repo in the default location, run the command:

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

Creating tags

You can create a tag for a specific version of a package.

To tag an existing image in a repository:

Console

Open the Repositories page in the Google Cloud console.

開啟「存放區」頁面
Click the package to view versions of the package.
Select the package version to tag.
In the row of the selected version, click More actions (), and then click Edit tags.
Type new tags into the field and then click SAVE.

gcloud

Run the following command:

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

Where

TAG is the tag you want to apply to the package.
PACKAGE is the name of the package in the repository.
VERSION is version of the package that you want to tag.
LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.
REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.

For example, to create the tag release-candidate for version 1.0.0 of package my-package in the repository my-repo in the default location, run the command:

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

Updating tags

You can change a tag associated with a package version.

To change an existing tag:

Console

Open the Repositories page in the Google Cloud console.

開啟「存放區」頁面
Click the package to view versions of the package.
Select the package version with the tag to change.
In the row of the selected version, click More actions (), and then click Edit tags.
Edit the tag and then click SAVE.

gcloud

Run the following command:

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

Where

TAG is the tag you want to apply to the package.
PACKAGE is the name of the package in the repository.
VERSION is version of the package that you want to tag.
LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.
REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.

For example, to change the tag for version 1.0.0 of package my-package to production in the repository my-repo in the default location, run the command:

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

Untagging package versions

You can remove an existing tag from a package version.

To remove a tag:

Console

Open the Repositories page in the Google Cloud console.

開啟「存放區」頁面
Click the image to view versions of the image.
Select the image version to untag.
In the row of the selected version, click More actions (), and then click Edit tags.
Delete the tag and then click SAVE.

gcloud

Run the following command:

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

Where

TAG is the tag you want to apply to the package.
PACKAGE is the name of the package in the repository.
LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.
REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.

For example, to remove the tag release-candidate from package my-package in the repository my-repo in the default location, run the command:

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 會在上游存放區中搜尋要求的套件。

如果沒有快取副本，上游遠端存放區就會下載並快取要求的套件。虛擬存放區只會提供所要求的套件，不會儲存這些套件。
如果您要求的版本在多個上游存放區中都有，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 控制台中開啟「Repositories」頁面。

開啟「存放區」頁面
在存放區清單中，按一下適當的存放區。

「Packages」頁面會列出存放區中的套件。
選取要刪除的套件。
按一下 [刪除]。
在確認對話方塊中，按一下「刪除」。

gcloud

執行下列指令：

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

更改下列內容：

PACKAGE 是存放區中的套件名稱。
REPOSITORY 是存放區的名稱。如果您已設定預設存放區，可以略過此標記，以便使用預設值。
LOCATION 是存放區的地區或多地區位置。使用這個旗標可查看特定位置的存放區。如果您已設定預設位置，則可以省略此標記，以便使用預設值。

--async 標記會讓指令立即傳回，而不會等待進行中的作業完成。

如要刪除套件版本，請按照下列步驟操作：

主控台

在 Google Cloud 控制台中開啟「Repositories」頁面。

開啟「存放區」頁面
在存放區清單中，按一下適當的存放區。

「Packages」頁面會列出存放區中的套件。
按一下套件即可查看該套件的版本。
選取要刪除的版本。
按一下 [刪除]。
在確認對話方塊中，按一下「刪除」。

gcloud

執行下列指令：

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

更改下列內容：

VERSION 是您要刪除的版本名稱。
PACKAGE 是存放區中的套件名稱。
REPOSITORY 是存放區的名稱。如果您已設定預設存放區，可以略過此標記，以便使用預設值。
LOCATION 是存放區的地區或多地區位置。使用這個旗標可查看特定位置的存放區。如果您已設定預設位置，則可以省略此標記，以便使用預設值。

--async 標記會讓指令立即傳回，而不會等待進行中的作業完成。

管理 Node.js 套件 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

必要的角色

取得存取權杖

新增套件

查看套件和版本

主控台

gcloud

列出檔案

範例

標記套件

Viewing tags

Console

gcloud

Creating tags

Console

gcloud

Updating tags

Console

gcloud

Untagging package versions

Console

gcloud

安裝套件

npm

yarn

刪除套件

主控台

gcloud

主控台

gcloud

後續步驟

管理 Node.js 套件