O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Gerenciar pacotes Node.js

Com o Artifact Registry, é possível publicar, organizar e instalar pacotes Node.js em repositórios no formato npm usando npm ou yarn. É possível ver pacotes e arquivos armazenados, gerenciar tags de versão, instalar dependências nos projetos e excluir ou descontinuar versões não usadas.

Antes de começar

Se não existir um repositório de destino, crie um novo repositório.
Verifique se você tem as permissões necessárias para o repositório.
Configure a autenticação do npm.
(Opcional) Configure padrões para comandos gcloud.
Se você estiver usando o ajudante de credenciais do npm para autenticação, receba um token de acesso antes de se conectar a um repositório com o npm.

Funções exigidas

Para receber as permissões necessárias para gerenciar pacotes, peça ao administrador para conceder a você os seguintes papéis do IAM no repositório:

Ver pacotes, arquivos em pacotes e tags: Leitor do Artifact Registry (roles/artifactregistry.reader)
Baixar ou instalar pacotes: Leitor do Artifact Registry (roles/artifactregistry.reader)
Adicionar pacotes a um repositório: Gravador do Artifact Registry (roles/artifactregistry.writer)
Excluir pacotes: Administrador do repositório do Artifact Registry (roles/artifactregistry.repoAdmin)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Como conseguir um token de acesso

Os tokens de acesso são válidos por 60 minutos. Gere um token de acesso pouco antes de executar comandos que interagem com repositórios.

Para receber um token, use uma destas opções:

Use o comando npx para atualizar o token de acesso.
1. Verifique se as credenciais para se conectar ao registro npm público estão no arquivo de configuração do npm do usuário, ~/.npmrc.
2. Execute o comando a seguir no diretório do projeto Node.js.
```
npx google-artifactregistry-auth
```
  Se o repositório do Artifact Registry estiver definido como seu registro global e os pacotes não estiverem no escopo, use o comando a seguir para que ele possa fazer o download do auxiliar de credenciais do registro público do npm em vez do repositório do Artifact Registry.
```
npm_config_registry=https://registry.npmjs.org npx google-artifactregistry-auth
```

Adicione um script ao arquivo package.json no seu projeto.

"scripts": {
 "artifactregistry-login": "npx google-artifactregistry-auth"
}

Execute o script no diretório do projeto Node.js.

npm run artifactregistry-login

O Artifact Registry lê as configurações do repositório no arquivo .npmrc do projeto e as usa para adicionar credenciais de token ao arquivo .npmrc do usuário. Armazenar o token no arquivo .npmrc do usuário isola suas credenciais do código-fonte e do sistema de controle de origem.

Como adicionar pacotes

Modos de repositório: padrão

Só é possível publicar uma versão específica de um pacote uma vez. Essa é uma restrição do npm para garantir que o conteúdo de uma versão publicada do pacote seja sempre o mesmo. Como resultado, você não poderá:

Substituir uma versão do pacote publicando-a novamente no repositório
Remover um pacote ou sua versão do repositório e, em seguida, publicar um pacote com o mesmo nome e número da versão

Se você não especificar uma tag ao publicar um pacote, o npm vai adicionar a tag latest. Para simplificar a instalação dos pacotes em uma etapa de desenvolvimento específica, considere publicar os pacotes com uma tag, como beta ou dev.

O Artifact Registry exige nomes de pacotes alfanuméricos em letras minúsculas para pacotes npm.

Para adicionar um pacote:

Verifique se o nome do pacote em package.json inclui o escopo configurado para seu repositório. O exemplo a seguir mostra um pacote com o escopo dev-repo.
```
"name": "@dev-repo/my-package"
```
Se você estiver usando o helper de credenciais para autenticar com um token de acesso, receba um novo token.
Adicione pacotes ao repositório. Use um comando npm ou yarn.

Para adicionar uma tag ao pacote, inclua a flag --tag e substitua TAG pela tag que você quer usar. Se você não incluir a flag --tag, o npm definirá automaticamente a tag como latest.
```
npm publish --tag=TAG
```
```
yarn publish --tag TAG
```

Como visualizar pacotes e versões

Modos de repositório:padrão, remoto, virtual

Para receber informações do pacote com npm ou yarn:

Se você estiver usando o helper de credenciais para autenticar com um token de acesso, receba um novo token.
Execute o comando adequado:
```
npm view
```
```
yarn info
```

Para visualizar pacotes e versões de pacotes usando o Google Cloud console ou gcloud:

Console

Abra a página Repositórios no Google Cloud console.

Abrir a página Repositórios
Na lista de repositórios, clique no repositório apropriado.

A página Pacotes lista os pacotes no repositório.
Clique em um pacote para visualizar as versões dele.

gcloud

Para listar pacotes em um repositório, execute o seguinte comando:

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

Substitua:

REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, você pode omitir essa sinalização para usar o padrão.
LOCATION é o local regional do repositório. Se você tiver configurado um local padrão, poderá omitir essa sinalização para usar o padrão.

Para ver as versões de um pacote, execute o seguinte comando:

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

Substitua:

PACKAGE é o ID do pacote ou o identificador totalmente qualificado do pacote.
REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, poderá omitir essa sinalização para usar o padrão.
LOCATION é o local regional do repositório. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa sinalização para usar o padrão.

A visualização de pacotes e versões no console do Google Cloud ou na CLI gcloud está disponível apenas para repositórios padrão e remotos.

Para repositórios remotos, a lista retornada precisa incluir todas as dependências diretas e transitivas armazenadas em cache no repositório.

Listar arquivos

Modos de repositório:padrão, remoto

É possível listar arquivos em um repositório, em todas as versões de um pacote especificado ou em uma versão específica de um pacote.

Para todos os comandos a seguir, é possível definir um número máximo de arquivos a serem retornados adicionando a flag --limit ao comando.

Para listar todos os arquivos no projeto, repositório e local padrão quando os valores padrão estão configurados:

gcloud artifacts files list

Para listar arquivos em um projeto, repositório e local especificados, execute o comando:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION

Para listar arquivos de todas as versões de um pacote específico:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE

Para listar arquivos de uma versão específica do pacote:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE \
    --version=VERSION

Para listar arquivos de uma tag específica:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE \
    --tag=TAG

Substitua os seguintes valores:

LOCATION: o local regional do repositório.
PROJECT: o ID do projeto do Google Cloud .
REPOSITORY: o nome do repositório em que a imagem está armazenada.
PACKAGE: o nome do pacote.
VERSION: a versão do pacote.
TAG: a tag associada ao pacote.

Exemplos

Considere as seguintes informações do pacote:

Projeto: my-project
Repositório: my-repo
Local do repositório:
Pacote: my-app

O comando a seguir lista todos os arquivos no repositório my-repo no local dentro do projeto padrão:

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

O comando a seguir lista os arquivos na versão 1.0 do pacote.

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

O comando a seguir lista os arquivos na versão do pacote com a tag 1.0-dev

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

Como marcar pacotes

Modos de repositório: padrão

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

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

查看标记

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

控制台

在 Google Cloud 控制台中打开代码库页面。

Abrir a página Repositórios
点击软件包以查看版本和关联的标记。
选择要标记的软件包版本。
在所选版本的行中，点击更多操作 ()，然后点击修改标记。
在字段中输入新标记，然后点击保存。

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

Abrir a página Repositórios
点击软件包以查看它的版本。
选择要标记的软件包版本。
在所选版本的行中，点击更多操作 ()，然后点击修改标记。
在字段中输入新标记，然后点击保存。

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

Abrir a página Repositórios
点击软件包以查看它的版本。
选择含有要更改的标记的软件包版本。
在所选版本的行中，点击更多操作 ()，然后点击修改标记。
修改标记，然后点击保存。

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

Abrir a página Repositórios
点击映像以查看映像的版本。
选择要取消标记的映像版本。
在所选版本的行中，点击更多操作 ()，然后点击修改标记。
删除标记，然后点击保存。

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

Como instalar pacotes

Modos de repositório:padrão, remoto, virtual

Para instalar um pacote do Package Repository do Node.js:

Se você estiver usando o helper de credenciais para autenticar com um token de acesso, receba um novo token.
Use o comando npm install ou yarn add.
npm
Para instalar a versão com a tag latest:
npm install @SCOPE/PACKAGE
Para instalar a versão com uma tag diferente:
npm install @SCOPE/PACKAGE@TAG
Para instalar uma versão específica:
npm install @SCOPE/PACKAGE@VERSION
yarn
Para instalar a versão com a tag latest:
yarn add @SCOPE/PACKAGE
Para instalar a versão com uma tag diferente:
yarn add @SCOPE/PACKAGE@TAG
Para instalar uma versão específica:
yarn add @SCOPE/PACKAGE@VERSION
Substitua os seguintes valores:
- SCOPE é o escopo associado ao repositório. Se o repositório de pacotes do Node.js não estiver configurado com um escopo, omita @SCOPE/ do comando.
- PACKAGE é o nome do pacote no repositório.
- TAG é a tag da versão que você quer instalar.
- VERSION é o número da versão que você quer instalar.

Ao especificar um pacote como uma dependência em package.json, inclua o escopo do repositório. O exemplo a seguir mostra o escopo @dev-repo de um pacote chamado my-package.

"dependencies": {
  "@dev-repo/my-package": ">=1.0.0"
}

Para repositórios padrão, você baixa um pacote diretamente do repositório.

Para um repositório remoto, faça o download de uma cópia em cache do pacote e das dependências dele. Se não houver uma cópia em cache, o repositório remoto vai fazer o download do pacote da origem upstream e armazená-lo em cache antes de disponibilizar para você. Para verificar se o repositório remoto recuperou os pacotes da fonte upstream, confira a lista de pacotes no repositório.

Para um repositório virtual, o Artifact Registry pesquisa nos repositórios upstream o pacote solicitado.

Os repositórios remotos upstream vão fazer o download e armazenar em cache o pacote solicitado se não houver uma cópia em cache. Os repositórios virtuais apenas atendem aos pacotes solicitados, não os armazenam.
Se você solicitar uma versão disponível em mais de um repositório upstream, o Artifact Registry vai escolher um repositório upstream com base nas configurações de prioridade configuradas para o repositório virtual.

Por exemplo, considere um repositório virtual com as seguintes configurações de prioridade para repositórios upstream:

main-repo: prioridade definida como 100
secondary-repo1: prioridade definida como 80.
secondary-repo2: prioridade definida como 80.
test-repo: prioridade definida como 20.

main-repo tem o maior valor de prioridade, então o repositório virtual sempre o pesquisa primeiro.

secondary-repo1 e secondary-repo2 têm prioridade definida como 80. Se um pacote solicitado não estiver disponível em main-repo, o Artifact Registry vai pesquisar nesses repositórios. Como ambos têm o mesmo valor de prioridade, o Artifact Registry pode veicular um pacote de qualquer um dos repositórios se a versão estiver disponível nos dois.

test-repo tem o menor valor de prioridade e vai disponibilizar um artefato armazenado se nenhum dos outros repositórios upstream tiver esse artefato.

Como excluir pacotes

Modos de repositório:padrão, remoto

É possível excluir um pacote e todas as versões dele ou uma versão específica.

Não é possível desfazer a exclusão de um pacote.
Para repositórios remotos, apenas a cópia em cache do pacote é excluída. A fonte upstream não é afetada. Se você excluir um pacote armazenado em cache, o Artifact Registry vai fazer o download e armazenar em cache novamente na próxima vez que o repositório receber uma solicitação para a mesma versão do pacote.

Depois que uma versão do pacote é publicada, não é possível republicar um pacote com o mesmo nome e combinação de versões, mesmo após excluir a versão. Essa é uma restrição do npm para garantir que o conteúdo de uma versão publicada do pacote seja sempre o mesmo.

Se você quiser incentivar os usuários a instalar uma versão atualizada do pacote, use o comando npm deprecate para marcar a versão antiga do pacote como obsoleta. Quando um usuário tenta instalar o pacote descontinuado, o Artifact Registry retorna um aviso de descontinuação.

Antes de excluir uma versão de pacote ou um pacote, verifique se você comunicou ou resolveu qualquer dependência importante nele.

Para excluir um pacote:

Console

Abra a página Repositórios no Google Cloud console.

Abrir a página Repositórios
Na lista de repositórios, clique no repositório apropriado.

A página Pacotes lista os pacotes no repositório.
Selecione o pacote que você quer excluir.
Clique em EXCLUIR.
Na caixa de diálogo de confirmação, clique em Excluir.

gcloud

Execute este comando:

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

Substitua:

PACKAGE é o nome do pacote no repositório.
REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, então poderá omitir essa sinalização para usar o padrão.
LOCATION é o local regional do repositório. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa sinalização para usar o padrão.

A sinalização --async faz com que o comando retorne imediatamente, sem aguardar a conclusão da operação.

Para excluir versões de um pacote:

Console

Abra a página Repositórios no Google Cloud console.

Abrir a página Repositórios
Na lista de repositórios, clique no repositório apropriado.

A página Pacotes lista os pacotes no repositório.
Clique em um pacote para visualizar as versões dele.
Selecione as versões que você quer excluir.
Clique em EXCLUIR.
Na caixa de diálogo de confirmação, clique em Excluir.

gcloud

Execute este comando:

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

Substitua:

VERSION é o nome da versão a ser excluída.
PACKAGE é o nome do pacote no repositório.
REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, então poderá omitir essa sinalização para usar o padrão.
LOCATION é o local regional do repositório. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa sinalização para usar o padrão.

A sinalização --async faz com que o comando retorne imediatamente, sem aguardar a conclusão da operação.

Gerenciar pacotes Node.js Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Funções exigidas

Como conseguir um token de acesso

Como adicionar pacotes

Como visualizar pacotes e versões

Console

gcloud

Listar arquivos

Exemplos

Como marcar pacotes

查看标记

控制台

gcloud

创建标记

控制台

gcloud

更新标记

控制台

gcloud

取消对软件包版本的标记

控制台

gcloud

Como instalar pacotes

npm

yarn

Como excluir pacotes

Console

gcloud

Console

gcloud

A seguir

Gerenciar pacotes Node.js