此页面由 Cloud Translation API 翻译。

管理 Node.js 软件包

本页介绍了以下任务：

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

准备工作

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

所需的角色

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

查看软件包、文件包中的文件和标记： Artifact Registry 读取者 (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 强制执行采用字母数字小写形式的软件包名称软件包

如需添加软件包，请执行以下操作：

确保 package.json 中的软件包名称包含 scope 中。以下示例展示了范围为 dev-repo 的软件包。
```
"name": "@dev-repo/my-package"
```
如果您使用的是凭据帮助程序使用访问令牌进行身份验证，请获取新令牌。
将软件包添加到代码库。您可以使用 npm 或 yarn 命令。

如需为软件包添加标记，请添加 --tag 标志，并将 TAG 替换为您要使用的标记。如果您未添加 --tag 标志，npm 会自动将标记设置为 latest。
```
npm publish --tag=TAG
```
```
yarn publish --tag TAG
```

查看软件包和版本

仓库模式：标准、远程、虚拟

如需使用 npm 或 yarn 获取软件包信息，请执行以下操作：

如果您使用凭据帮助程序使用访问令牌进行身份验证，请获取新的令牌。
运行相应的命令：
```
npm view
```
```
yarn info
```

如需使用 Google Cloud 控制台或 gcloud 查看软件包和软件包版本，请执行以下操作：

控制台

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

打开“代码库”页面
在代码库列表中，点击相应代码库。

软件包页面列出代码库中的软件包。
点击一个软件包以查看它的版本。

gcloud

如需列出代码库中的软件包，请运行以下命令：

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

地点

REPOSITORY 是代码库的名称。如果您配置了默认代码库，则可以省略此标志以使用默认值。
LOCATION是单区域或多区域 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

以下命令将列出 my-repo 中默认项目中的位置 us-west1：

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。这样，您的团队就可以根据标记（而非版本说明符）安装正确的版本，并且取消发布未使用的预发布版本不会破坏您对候选版本软件包的依赖项。

查看标记

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

控制台

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

打开“代码库”页面
点击软件包以查看版本和关联的标记。
选择要标记的软件包版本。
在所选版本的行中，点击更多操作 ()，然后点击修改标记。
在字段中输入新标记，然后点击保存。

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

创建标记

您可以为特定版本的软件包创建标记。

如需标记代码库中的现有映像，请执行以下操作：

控制台

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

打开“代码库”页面
点击软件包以查看它的版本。
选择要标记的软件包版本。
在所选版本的行中，点击更多操作 ()，然后点击修改标记。
在字段中输入新标记，然后点击保存。

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

更新标记

您可以更改与软件包版本关联的标记。

如需更改现有标记，请执行以下操作：

控制台

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

打开“代码库”页面
点击软件包以查看它的版本。
选择含有要更改的标记的软件包版本。
在所选版本的行中，点击更多操作 ()，然后点击修改标记。
修改标记，然后点击保存。

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

取消对软件包版本的标记

您可以从软件包版本中移除现有标记。

如需移除标记，请执行以下操作：

控制台

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

打开“代码库”页面
点击映像以查看映像的版本。
选择要取消链接的图片版本。
在所选版本的行中，点击更多操作 ()，然后点击修改标记。
删除标记，然后点击保存。

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

如果您使用凭据帮助程序使用访问令牌进行身份验证，请获取新的令牌。
使用 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 会返回弃用警告。

在删除软件包或软件包版本之前，请确认您已在其中告知或解决任何重要依赖项。

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

控制台

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

打开“代码库”页面
在代码库列表中，点击相应代码库。

软件包页面列出代码库中的软件包。
选择要删除的软件包。
点击删除。
在确认对话框中，点击删除。

gcloud

运行以下命令：

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

地点

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

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

控制台

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

打开“代码库”页面
在代码库列表中，点击相应代码库。

软件包页面列出代码库中的软件包。
点击一个软件包以查看它的版本。
选择您要删除的版本。
点击删除。
在确认对话框中，点击删除。

gcloud

运行以下命令：

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

地点

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

管理 Node.js 软件包

准备工作

所需的角色

获取访问令牌

添加软件包

查看软件包和版本

控制台

gcloud

列出文件

示例

标记软件包

查看标记

控制台

gcloud

创建标记

控制台

gcloud

更新标记

控制台

gcloud

取消对软件包版本的标记

控制台

gcloud

安装软件包

npm

yarn

删除软件包

控制台

gcloud

控制台

gcloud

后续步骤