Gestire i pacchetti Node.js

Questa pagina descrive le seguenti attività:

Visualizzazione ed eliminazione di pacchetti e versioni dei pacchetti
Visualizzazione, creazione, aggiornamento ed eliminazione dei tag

Prima di iniziare

Se il repository di destinazione non esiste, creane uno nuovo.
Verifica di disporre delle autorizzazioni richieste per il repository.
Configura l'autenticazione per npm.
(Facoltativo) Configura le impostazioni predefinite per i comandi gcloud.
Se utilizzi l'helper delle credenziali npm per l'autenticazione, ottieni un token di accesso prima di connetterti a un repository con npm.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per gestire i pacchetti, chiedi all'amministratore di concederti i seguenti ruoli IAM nel repository:

Visualizza pacchetti, file nei pacchetti e tag: Lettore Artifact Registry (roles/artifactregistry.reader)
Scarica o installa pacchetti: Artifact Registry Reader (roles/artifactregistry.reader)
Aggiungi pacchetti a un repository: Scrittore Artifact Registry (roles/artifactregistry.writer)
Elimina pacchetti: Amministratore repository Artifact Registry (roles/artifactregistry.repoAdmin)

Per ulteriori informazioni sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Ottenere un token di accesso

I token di accesso sono validi per 60 minuti. Genera un token di accesso poco prima di eseguire comandi che interagiscono con i repository.

Per ottenere un token, utilizza una di queste opzioni:

Utilizza il comando npx per aggiornare il token di accesso.
1. Assicurati che le credenziali per la connessione al registro npm pubblico si trovino nel file di configurazione npm dell'utente, ~/.npmrc.
2. Esegui questo comando nella directory del progetto Node.js.
```
npx google-artifactregistry-auth
```
  Se il repository Artifact Registry è impostato come registro globale e i pacchetti non sono inclusi nell'ambito, utilizza il seguente comando in modo che possa scaricare l'helper delle credenziali dal registro npm pubblico anziché dal repository Artifact Registry.
```
npm_config_registry=https://registry.npmjs.org npx google-artifactregistry-auth
```

Aggiungi uno script al file package.json del progetto.

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

Esegui lo script nella directory del progetto Node.js.

npm run artifactregistry-login

Artifact Registry legge le impostazioni del repository Artifact Registry nel file .npmrc del progetto e le utilizza per aggiungere le credenziali token al file .npmrc dell'utente. L'archiviazione del token nel file .npmrc dell'utente isola le tue credenziali dal codice sorgente e dal sistema di controllo del codice sorgente.

Aggiunta di pacchetti

Modalità repository: standard

Puoi pubblicare una versione specifica di un pacchetto una sola volta. Si tratta di una limitazione di npm per garantire che i contenuti di una versione del pacchetto pubblicata siano sempre gli stessi. Di conseguenza, non puoi:

Sovrascrivere una versione del pacchetto pubblicandola di nuovo nel repository
Rimuovi un pacchetto o la relativa versione dal repository, quindi pubblica un pacchetto con lo stesso nome e numero di versione

Se non specifichi un tag quando pubblichi un pacchetto, npm aggiunge il tag latest. Per semplificare l'installazione dei pacchetti in una fase di sviluppo specifica, valuta la possibilità di pubblicarli con un tag, ad esempio beta o dev.

Artifact Registry applica nomi di pacchetti alfanumerici minuscoli per i pacchetti npm.

Per aggiungere un pacchetto:

Assicurati che il nome del pacchetto in package.json includa l'ambito configurato per il repository. L'esempio seguente mostra un pacchetto con l'ambito dev-repo.
```
"name": "@dev-repo/my-package"
```
Se utilizzi l'helper delle credenziali per l'autenticazione con un token di accesso, ottieni un nuovo token.
Aggiungi pacchetti al repository. Puoi utilizzare un comando npm o yarn.

Per taggare il pacchetto, includi il flag --tag e sostituisci TAG con il tag che vuoi utilizzare. Se non includi il flag --tag, npm imposta automaticamente il tag su latest.
```
npm publish --tag=TAG
```
```
yarn publish --tag TAG
```

Visualizzazione di pacchetti e versioni

Modalità repository: standard, remoto, virtuale

Per ottenere informazioni sul pacco con npm o yarn:

Se utilizzi l'helper delle credenziali per l'autenticazione con un token di accesso, ottieni un nuovo token.
Esegui il comando appropriato:
```
npm view
```
```
yarn info
```

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

Console

Open the Repositories page in the Google Cloud console.

Apri la pagina Repositori
In the repository list, click the appropriate repository.

The Packages page lists the packages in the repository.
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.

La visualizzazione di pacchetti e versioni dalla console Google Cloud o da gcloud CLI è disponibile solo per i repository standard e remoti.

Per i repository remoti, l'elenco restituito deve includere tutte le dipendenze dirette e transitive memorizzate nella cache del repository.

Elenco dei file

Modalità repository: standard, remoto

Puoi elencare i file in un repository, i file in tutte le versioni di un pacchetto specificato o i file in una versione specifica di un pacchetto.

Per tutti i comandi seguenti, puoi impostare un numero massimo di file da restituire aggiungendo il flag --limit al comando.

Per elencare tutti i file nel progetto, nel repository e nella posizione predefiniti quando sono configurati i valori predefiniti:

gcloud artifacts files list

Per elencare i file in un progetto, un repository e una località specifici, esegui il comando:

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

Per elencare i file per tutte le versioni di un pacchetto specifico:

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

Per elencare i file per una versione specifica del pacchetto:

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

Per elencare i file per un tag specifico:

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

Sostituisci i seguenti valori:

LOCATION: la posizione regionale o multiregionale del repository.
PROJECT: il tuo Google Cloud ID progetto. Se l'ID progetto contiene due punti (:), consulta Progetti basati sul dominio.
REPOSITORY: il nome del repository in cui è archiviata l'immagine.
PACKAGE: il nome del pacchetto.
VERSION: la versione del pacchetto.
TAG: il tag associato al pacchetto.

Esempi

Considera le seguenti informazioni sul pacchetto:

Progetto: my-project
Repository: my-repo
Posizione del repository: us-west1
Pacchetto: my-app

Il comando seguente elenca tutti i file nel repository my-repo nella posizione us-west1 all'interno del progetto predefinito:

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

Il seguente comando elenca i file nella versione 1.0 del pacchetto.

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

Il comando seguente elenca i file nella versione del pacchetto con il tag 1.0-dev

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

Pacchetti di tagging

Modalità repository: standard

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.

Apri la pagina Repositori
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.

Apri la pagina Repositori
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.

Apri la pagina Repositori
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.

Apri la pagina Repositori
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

Installazione dei pacchetti

Modalità repository: standard, remoto, virtuale

Per installare un pacchetto dal repository di pacchetti Node.js:

Se utilizzi l'helper delle credenziali per l'autenticazione con un token di accesso, ottieni un nuovo token.
Utilizza il comando npm install o yarn add.
npm
Per installare la versione con il tag latest:
```
npm install @SCOPE/PACKAGE
```
Per installare la versione con un tag diverso:
```
npm install @SCOPE/PACKAGE@TAG
```
Per installare una versione specifica:
```
npm install @SCOPE/PACKAGE@VERSION
```
filato
Per installare la versione con il tag latest:
```
yarn add @SCOPE/PACKAGE
```
Per installare la versione con un tag diverso:
```
yarn add @SCOPE/PACKAGE@TAG
```
Per installare una versione specifica:
```
yarn add @SCOPE/PACKAGE@VERSION
```
Sostituisci i seguenti valori:
- SCOPE è l'ambito associato al repository. Se il repository del pacchetto Node.js non è configurato con un ambito, ometti @SCOPE/ dal comando.
- PACKAGE è il nome del pacchetto nel repository.
- TAG è il tag della versione che vuoi installare.
- VERSION è il numero di versione che vuoi installare.

Quando specifichi un pacchetto come dipendenza in package.json, assicurati di includere l'ambito per il repository. L'esempio seguente mostra l'ambito @dev-repo per un pacchetto denominato my-package.

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

Per i repository standard, scarichi un pacchetto direttamente dal repository.

Per un repository remoto, scarichi una copia memorizzata nella cache del pacchetto e delle relative dipendenze. Se non esiste una copia memorizzata nella cache, il repository remoto scarica il pacchetto dalla sorgente upstream e lo memorizza nella cache prima di fornirtelo. Puoi verificare che il repository remoto abbia recuperato i pacchetti dalla sorgente upstream visualizzando l'elenco dei pacchetti nel repository.

Per un repository virtuale, Artifact Registry cerca il pacchetto richiesto nei repository upstream.

I repository remoti upstream scaricano e memorizzano nella cache il pacchetto richiesto se non esiste una copia memorizzata nella cache. I repository virtuali forniscono solo i pacchetti richiesti, non li archiviano.
Se richiedi una versione disponibile in più di un repository upstream, Artifact Registry sceglie un repository upstream da utilizzare in base alle impostazioni di priorità configurate per il repository virtuale.

Ad esempio, considera un repository virtuale con le seguenti impostazioni di priorità per i repository upstream:

main-repo: priorità impostata su 100
secondary-repo1: priorità impostata su 80.
secondary-repo2: priorità impostata su 80.
test-repo: priorità impostata su 20.

main-repo ha il valore di priorità più alto, quindi il repository virtuale lo cerca sempre per primo.

Sia secondary-repo1 che secondary-repo2 hanno la priorità impostata su 80. Se un pacchetto richiesto non è disponibile in main-repo, Artifact Registry esegue la ricerca in questi repository. Poiché hanno lo stesso valore di priorità, Artifact Registry può scegliere di pubblicare un pacchetto da uno dei due repository se la versione è disponibile in entrambi.

test-repo ha il valore di priorità più basso e servirà un artefatto archiviato se nessuno degli altri repository upstream lo contiene.

Eliminazione dei pacchetti

Modalità repository: standard, remoto

Puoi eliminare un pacchetto e tutte le relative versioni oppure eliminare una versione specifica.

Una volta eliminato un pacchetto, non puoi annullare l'azione.
Per i repository remoti, viene eliminata solo la copia memorizzata nella cache del pacchetto. L'origine a monte non è interessata. Se elimini un pacchetto memorizzato nella cache, Artifact Registry lo scaricherà e memorizzerà nuovamente nella cache la volta successiva che il repository riceve una richiesta per la stessa versione del pacchetto.

Una volta pubblicata una versione del pacchetto, non puoi ripubblicare un pacchetto con la stessa combinazione di nome e versione, anche dopo aver eliminato la versione. Si tratta di una limitazione di npm per garantire che i contenuti di una versione del pacchetto pubblicata siano sempre gli stessi.

Se vuoi incoraggiare gli utenti a installare una versione aggiornata del pacchetto, utilizza il comando npm deprecate per contrassegnare la vecchia versione del pacchetto come obsoleta. Quando un utente tenta di installare il pacchetto ritirato, Artifact Registry restituisce un avviso di ritiro.

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

Open the Repositories page in the Google Cloud console.

Apri la pagina Repositori
In the repository list, click the appropriate repository.

The Packages page lists the packages in the repository.
Select the package that you want to delete.
Click DELETE.
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

Open the Repositories page in the Google Cloud console.

Apri la pagina Repositori
In the repository list, click the appropriate repository.

The Packages page lists the packages in the repository.
Click a package to view versions of that package.
Select versions that you want to delete.
Click DELETE.
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.

Gestire i pacchetti Node.js Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Prima di iniziare

Ruoli obbligatori

Ottenere un token di accesso

Aggiunta di pacchetti

Visualizzazione di pacchetti e versioni

Console

gcloud

Elenco dei file

Esempi

Pacchetti di tagging

Viewing tags

Console

gcloud

Creating tags

Console

gcloud

Updating tags

Console

gcloud

Untagging package versions

Console

gcloud

Installazione dei pacchetti

npm

filato

Eliminazione dei pacchetti

Console

gcloud

Console

gcloud

Passaggi successivi

Gestire i pacchetti Node.js