管理 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 注册表的凭据位于用户的 npm 配置文件 ~/.npmrc 中。

  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 控制台中的制品库页面。

   打开“代码库”页面

2. 在代码库列表中，点击相应代码库。

   软件包页面列出代码库中的软件包。

3. 点击一个软件包以查看它的版本。

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-central1
• 软件包：my-app

以下命令用于列出代码库 my-repo 中位于默认项目位置 us-central1 中的所有文件：

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

以下命令用于列出软件包 1.0 版本中的文件。

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

以下命令会列出软件包版本中具有 1.0-dev 标记的文件

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

为软件包添加代码

代码库模式：标准

您可以查看、添加、更新和删除代码。标记可帮助您管理软件包的语义版本，并简化在特定开发阶段的软件包安装。

例如，您可以使用 rc 标记当前的候选版本 build。然后，您的团队可以根据标记（而不是版本说明符）安装正确的版本，并且取消发布未使用的预发布版本不会破坏您对候选版本软件包的依赖关系。

查看标记

如需查看软件包的标记，请执行以下操作：

控制台

1. 打开 Google Cloud 控制台中的制品库页面。

   打开“代码库”页面

2. 点击软件包以查看版本和关联的标记。

3. 选择要标记的软件包版本。

4. 在所选版本的行中，点击更多操作 ()，然后点击修改标记。

5. 在字段中输入新标记，然后点击保存。

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 控制台中的制品库页面。

   打开“代码库”页面

2. 点击软件包以查看它的版本。

3. 选择要标记的软件包版本。

4. 在所选版本的行中，点击更多操作 ()，然后点击修改标记。

5. 在字段中输入新标记，然后点击保存。

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 控制台中的制品库页面。

   打开“代码库”页面

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 控制台中的制品库页面。

   打开“代码库”页面

2. 点击映像以查看映像的版本。

3. 选择要取消标记的映像版本。

4. 在所选版本的行中，点击更多操作 ()，然后点击修改标记。

5. 删除标记，然后点击保存。

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
   

   纱线

   如需使用 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 控制台中的制品库页面。

   打开“代码库”页面

2. 在代码库列表中，点击相应代码库。

   软件包页面列出代码库中的软件包。

3. 选择要删除的软件包。

4. 点击删除。

5. 在确认对话框中，点击删除。

gcloud

运行以下命令：

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

地点

• PACKAGE 是代码库中的软件包名称。
• REPOSITORY 是代码库的名称。如果您配置了默认代码库，则可以省略此标志以使用默认值。
• LOCATION 是单区域或多区域位置。使用此标志可查看特定位置的代码库。如果您配置了默认位置，可以省略此标志，以便使用默认位置。
• --async 会立即返回结果，而无需等待正在进行的操作完成。

如需删除软件包的版本，请按如下所述操作：

控制台

1. 打开 Google Cloud 控制台中的制品库页面。

   打开“代码库”页面

2. 在代码库列表中，点击相应代码库。

   软件包页面列出代码库中的软件包。

3. 点击一个软件包以查看它的版本。

4. 选择您要删除的版本。

5. 点击删除。

6. 在确认对话框中，点击删除。

gcloud

运行以下命令：

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

地点

• PACKAGE 是代码库中的软件包名称。
• REPOSITORY 是代码库的名称。如果您配置了默认代码库，则可以省略此标志以使用默认值。
• LOCATION 是单区域或多区域位置。使用此标志可查看特定位置的代码库。如果您配置了默认位置，可以省略此标志，以便使用默认位置。
• --async 会立即返回结果，而无需等待正在进行的操作完成。

后续步骤

• 了解如何管理 Maven 软件包
• 了解如何管理容器映像
• 下载软件包中的个别文件