管理 Node.js 套件

本頁面說明下列工作：

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

事前準備

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

必要的角色

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

• 查看套件、套件中的檔案和標記： Artifact Registry Reader (roles/artifactregistry.reader)
• 下載或安裝套件： Artifact Registry Reader (roles/artifactregistry.reader)
• 將套件新增至存放區： Artifact Registry Writer (roles/artifactregistry.writer)
• 刪除套件： Artifact Registry Repository Administrator (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 套件使用小寫英數字元套件名稱。

如要新增套件，請按照下列步驟操作：

1. 請確認 package.json 中的套件名稱包含為存放區設定的範圍。以下範例顯示範圍為 dev-repo 的套件。

   "name": "@dev-repo/my-package"
   

2. 如果您使用憑證輔助程式驗證存取權杖，請取得新的權杖。

3. 將套件新增至存放區。您可以使用 npm 或 yarn 指令。

   如要標記套件，請加入 --tag 旗標，並將 TAG 替換為要使用的標記。如果未加入 --tag 標記，npm 會自動將標記設為 latest。

   npm publish --tag=TAG
   

   yarn publish --tag TAG
   

查看套件和版本

存放區模式：標準、遠端、虛擬

如要使用 npm 或 yarn 取得套件資訊，請按照下列步驟操作：

1. 如果您使用憑證輔助程式驗證存取權杖，請取得新的權杖。

2. 執行適當指令：

   npm view
   

   yarn info
   

如要使用 Google Cloud 控制台或 gcloud 查看套件和套件版本，請按照下列步驟操作：

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

gcloud artifacts versions list --package=PACKAGE \
    [--repository=REPOSITORY] [--location=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

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

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

為套件加上標記

存放區模式：標準

您可以查看、新增、更新及刪除標記。標記可協助您管理套件的語意版本，並在特定開發階段簡化套件安裝作業。

舉例來說，您可以使用 rc 標記目前的候選版本。這樣一來，您的團隊就能根據標記 (而非版本指定詞) 安裝正確的版本，且取消發布未使用的預發布版本，也不會破壞您對候選版本套件依附元件的依附元件。

查看代碼

如何查看套件的標記：

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

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

建立代碼

您可以為特定套件版本建立標記。

如要在存放區中標記現有圖片，請按照下列步驟操作：

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

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

更新標記

您可以變更與套件版本相關聯的標記。

如要變更現有標記，請按照下列步驟操作：

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

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

取消套用套件版本標記

您可以從套件版本中移除現有標記。

如要移除標記，請按照下列步驟操作：

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

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

安裝套件

存放區模式：標準、遠端、虛擬

如何從 Node.js 套件存放區安裝套件：

1. 如果您使用憑證輔助程式驗證存取權杖，請取得新的權杖。

2. 請使用 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 淘汰指令，將套件的舊版本標示為已淘汰。當使用者嘗試安裝已淘汰的套件時，Artifact Registry 會傳回淘汰警告。

刪除套件或套件版本前，請確認您已通報或解決其中的任何重要依附元件。

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

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

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

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

後續步驟

• 瞭解如何管理 Maven 套件
• 瞭解如何管理容器映像檔
• 下載套件中的個別檔案