管理 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 查看软件包和软件包版本，请执行以下操作：

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

标记软件包

代码库模式：标准

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:

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

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:

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

Updating tags

You can change a tag associated with a package version.

To change an existing tag:

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

Untagging package versions

You can remove an existing tag from a package version.

To remove a tag:

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 deprecate 命令将旧版软件包标记为已弃用。当用户尝试安装已弃用的软件包时，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 软件包
• 了解如何管理容器映像
• 下载软件包中的单个文件