管理 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-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 为当前的候选版本 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
   

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

   打开“代码库”页面

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]

替换以下内容：

• VERSION 是要删除的版本的名称。
• PACKAGE 是代码库中的软件包名称。
• REPOSITORY 是代码库的名称。如果您配置了默认代码库，则可以省略此标志以使用默认值。
• LOCATION 是代码库的单区域或多区域位置。 使用此标志可查看特定位置的代码库。如果您配置了默认位置，则可以省略此标志以使用默认值。

--async 标志会导致命令立即返回，而无需等待正在进行的操作完成。

后续步骤

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