Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Gerenciar pacotes Node.js

Nesta página, descrevemos as seguintes tarefas:

Como visualizar e excluir pacotes e versões de pacote
Como visualizar, criar, atualizar e excluir tags

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 auxiliar de credenciais do npm credential helper para autenticação, receba um token de acesso antes de se conectar a um repositório com o npm.

Funções exigidas

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

Visualizar pacotes, arquivos em pacotes e tags: leitor do Artifact Registry (roles/artifactregistry.reader)
Fazer o download 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 personalizados papéis ou outros predefinidos papéis.

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 o registro global e os pacotes não estiverem no escopo, use o comando a seguir para que o comando possa fazer o download do auxiliar de credenciais do registro npm público 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 do Artifact Registry 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 npm para garantir que o conteúdo de uma versão de pacote publicada 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 um estágio de desenvolvimento específico, considere publicar os pacotes com uma tag, como beta ou dev.

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

Para adicionar um pacote:

Certifique-se de que o nome do pacote em package.json inclua 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 auxiliar de credenciais para autenticar com um token de acesso, obtenha um novo token.
Adicione pacotes ao repositório. Use um comando npm ou yarn.

Para marcar o pacote, inclua a --tag flag e substitua TAG pela tag que você quer usar. Se você não incluir a flag --tag, o npm vai 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 auxiliar de credenciais para autenticar com um token de acesso, obtenha um novo token.
Execute o comando apropriado:
```
npm view
```
```
yarn info
```

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

Console

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

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, poderá omitir essa flag para usar o padrão.
LOCATION é o local regional ou multirregional do repositório. Se você configurou um local padrão, pode omitir essa flag 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 flag para usar o padrão.
LOCATION é o local regional ou multirregional do repositório. Use esta flag para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa flag para usar o padrão.

A visualização de pacotes e versões de Google Cloud console ou da CLI gcloud só está disponível 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.

Como listar arquivos

Modos de repositório: padrão, remoto

É possível listar arquivos em um repositório, arquivos em todas as versões de um pacote especificado ou arquivos 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 estiverem 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 ou multirregional do repositório.
PROJECT: o ID do projeto Google Cloud . Se o ID do projeto tiver dois pontos (:), consulte Projetos com escopo de domínio.
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: us-west1
Pacote: my-app

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

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

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

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

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

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

Como marcar pacotes

Modos de repositório: padrão

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

Open the Repositories page in the Google Cloud console.

Abrir a página Repositórios
Click the package to view versions and the associated tags.
Select the package version to tag.
In the row of the selected version, click More actions (), and then click Edit tags.
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

Open the Repositories page in the Google Cloud console.

Abrir a página Repositórios
Click the package to view versions of the package.
Select the package version to tag.
In the row of the selected version, click More actions (), and then click Edit tags.
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

Open the Repositories page in the Google Cloud console.

Abrir a página Repositórios
Click the package to view versions of the package.
Select the package version with the tag to change.
In the row of the selected version, click More actions (), and then click Edit tags.
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

Open the Repositories page in the Google Cloud console.

Abrir a página Repositórios
Click the image to view versions of the image.
Select the image version to untag.
In the row of the selected version, click More actions (), and then click Edit tags.
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

Como instalar pacotes

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

Para instalar um pacote do repositório de pacotes Node.js:

Se você estiver usando o auxiliar de credenciais para autenticar com um token de acesso, obtenha 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 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, faça o download de 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 fará o download do pacote da origem upstream e o armazenará em cache antes de disponibilizá-lo para você. É possível verificar se o repositório remoto recuperou os pacotes da origem upstream visualizando a lista de pacotes no repositório.

Para um repositório virtual, o Artifact Registry pesquisa repositórios upstream para 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 só disponibilizam pacotes solicitados, eles 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 para usar 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 valor de prioridade mais alto. Portanto, o repositório virtual sempre o pesquisa primeiro.

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

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

Como excluir pacotes

Modos de repositório: padrão, remoto

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

Depois de excluir um pacote, não é possível desfazer a ação.
Para repositórios remotos, apenas a cópia em cache do pacote é excluída. A origem upstream não é afetada. Se você excluir um pacote armazenado em cache, o Artifact Registry vai fazer o download e armazená-lo 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 npm para garantir que o conteúdo de uma versão de pacote publicada 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 suspensão de uso.

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 console do Google Cloud .

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, poderá omitir essa flag para usar o padrão.
LOCATION é o local regional ou multirregional do repositório. Use esta flag para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa flag para usar o padrão.

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

Para excluir versões de um pacote:

Console

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

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, poderá omitir essa flag para usar o padrão.
LOCATION é o local regional ou multirregional do repositório. Use esta flag para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa flag para usar o padrão.

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

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

Como listar arquivos

Exemplos

Como marcar pacotes

Viewing tags

Console

gcloud

Creating tags

Console

gcloud

Updating tags

Console

gcloud

Untagging package versions

Console

gcloud

Como instalar pacotes

npm

yarn

Como excluir pacotes

Console

gcloud

Console

gcloud

A seguir

Gerenciar pacotes Node.js