管理 Node.js 软件包

本页面介绍了以下任务：

  • 查看和删除软件包与软件包版本
  • 查看、创建、更新和删除标记

准备工作

  1. 如果目标代码库不存在，请创建新代码库。
  2. 验证您是否拥有访问代码库所需的权限。
  3. 为 npm 配置身份验证。
  4. （可选）为 gcloud 命令配置默认值。
  5. 如果您使用 npm 凭据帮助程序进行身份验证，请先获取访问令牌，然后再使用 npm 连接到代码库。

所需的角色

如需获得管理软件包所需的权限，请让管理员向您授予代码库的以下 IAM 角色：

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

获取访问令牌

访问令牌的有效期为 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

To view packages and package versions using the Google Cloud console or gcloud:

Console

  1. Open the Repositories page in the Google Cloud console.

    打开“代码库”页面

  2. In the repository list, click the appropriate repository.

    The Packages page lists the packages in the repository.

  3. Click a package to view versions of the package.

gcloud

To list packages in a repository, run the following command:

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

Replace the following:

  • REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.
  • LOCATION is the regional or multi-regional location of the repository. If you configured a default location, then you can omit this flag to use the default.

To view versions of a package, run the following command:

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

Replace the following:

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

只能从 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

  1. Open the Repositories page in the Google Cloud console.

    打开“代码库”页面

  2. Click the package to view versions and the associated tags.

  3. Select the package version to tag.

  4. In the row of the selected version, click More actions (More actions), and then click Edit tags.

  5. 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

  1. Open the Repositories page in the Google Cloud console.

    打开“代码库”页面

  2. Click the package to view versions of the package.

  3. Select the package version to tag.

  4. In the row of the selected version, click More actions (More actions), and then click Edit tags.

  5. 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

  1. Open the Repositories page in the Google Cloud console.

    打开“代码库”页面

  2. Click the package to view versions of the package.

  3. Select the package version with the tag to change.

  4. In the row of the selected version, click More actions (More actions), and then click Edit tags.

  5. 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

  1. Open the Repositories page in the Google Cloud console.

    打开“代码库”页面

  2. Click the image to view versions of the image.

  3. Select the image version to untag.

  4. In the row of the selected version, click More actions (More actions), and then click Edit tags.

  5. 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 软件包代码库安装软件包，请执行以下操作：

  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 会返回弃用警告。

Before you delete a package or package version, verify that any you have communicated or addressed any important dependencies on it.

To delete a package:

Console

  1. Open the Repositories page in the Google Cloud console.

    打开“代码库”页面

  2. In the repository list, click the appropriate repository.

    The Packages page lists the packages in the repository.

  3. Select the package that you want to delete.

  4. Click DELETE.

  5. In the confirmation dialog box, click DELETE.

gcloud

Run the following command:

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

Replace the following:

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

The --async flag causes the command to return immediately, without waiting for the operation in progress to complete.

To delete versions of a package:

Console

  1. Open the Repositories page in the Google Cloud console.

    打开“代码库”页面

  2. In the repository list, click the appropriate repository.

    The Packages page lists the packages in the repository.

  3. Click a package to view versions of that package.

  4. Select versions that you want to delete.

  5. Click DELETE.

  6. In the confirmation dialog box, click DELETE.

gcloud

Run the following command:

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

Replace the following:

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

The --async flag causes the command to return immediately, without waiting for the operation in progress to complete.

后续步骤