管理 Node.js 套件

本頁面說明下列工作：

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

事前準備

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

必要的角色

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

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

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

取得存取權杖

存取權杖的效期為 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 查看套件和套件版本，請按照下列步驟操作：

控制台

  1. 在 Google Cloud 控制台中開啟「Repositories」(存放區) 頁面。

    開啟「存放區」頁面

  2. 在存放區清單中，按一下適當的存放區。

    「Packages」(套件) 頁面會列出存放區中的套件。

  3. 按一下套件即可查看套件版本。

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

標記套件

存放區模式：標準

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

舉例來說，您可以為目前的候選版本建構項目加上 rc 標記。這樣一來，團隊就能根據標記安裝正確版本，而非版本指定符，且取消發布未使用的預先發布版本時，也不會中斷對候選版套件的依附元件。

查看代碼

如要查看套件的標記：

控制台

  1. 在 Google Cloud 控制台中開啟「Repositories」(存放區) 頁面。

    開啟「存放區」頁面

  2. 按一下套件即可查看版本和相關聯的標記。

  3. 選取要標記的套件版本。

  4. 在所選版本的資料列中，按一下「更多動作」 (更多動作)，然後按一下「編輯代碼」。

  5. 在欄位中輸入新的標記，然後按一下 [SAVE] (儲存)。

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

建立標記

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

如要標記存放區中的現有映像檔，請按照下列步驟操作：

控制台

  1. 在 Google Cloud 控制台中開啟「Repositories」(存放區) 頁面。

    開啟「存放區」頁面

  2. 按一下檔案包即可查看檔案包版本。

  3. 選取要標記的套件版本。

  4. 在所選版本的資料列中，按一下「更多動作」 (更多動作)，然後按一下「編輯代碼」。

  5. 在欄位中輸入新的標記，然後按一下 [SAVE] (儲存)。

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

更新標記

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

如要變更現有代碼：

控制台

  1. 在 Google Cloud 控制台中開啟「Repositories」(存放區) 頁面。

    開啟「存放區」頁面

  2. 按一下檔案包即可查看檔案包版本。

  3. 選取要變更標記的套件版本。

  4. 在所選版本的資料列中，按一下「更多動作」 (更多動作)，然後按一下「編輯代碼」。

  5. 編輯標記，然後按一下「儲存」。

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

取消標記套件版本

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

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

控制台

  1. 在 Google Cloud 控制台中開啟「Repositories」(存放區) 頁面。

    開啟「存放區」頁面

  2. 按一下圖片即可查看版本。

  3. 選取要取消標記的圖片版本。

  4. 在所選版本的資料列中，按一下「更多動作」 (更多動作)，然後按一下「編輯代碼」。

  5. 刪除標記，然後按一下 [SAVE] (儲存)。

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 套件存放區安裝套件，請按照下列步驟操作：

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

刪除套件或套件版本前，請先確認您已傳達或解決所有重要的相依性。

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

控制台

  1. 在 Google Cloud 控制台中開啟「Repositories」(存放區) 頁面。

    開啟「存放區」頁面

  2. 在存放區清單中，按一下適當的存放區。

    「Packages」(套件) 頁面會列出存放區中的套件。

  3. 選取要刪除的套件。

  4. 按一下 [刪除]。

  5. 在確認對話方塊中，按一下「刪除」。

gcloud

執行下列指令：

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

更改下列內容：

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

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

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

控制台

  1. 在 Google Cloud 控制台中開啟「Repositories」(存放區) 頁面。

    開啟「存放區」頁面

  2. 在存放區清單中，按一下適當的存放區。

    「Packages」(套件) 頁面會列出存放區中的套件。

  3. 按一下套件即可查看該套件的版本。

  4. 選取要刪除的版本。

  5. 按一下 [刪除]。

  6. 在確認對話方塊中，按一下「刪除」。

gcloud

執行下列指令：

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

更改下列內容：

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

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

後續步驟