Specifica le dipendenze in Node.js

Una funzione può utilizzare moduli Node.js esterni e dati locali. Le dipendenze in Node.js vengono gestite con npm ed espresse in un file di metadati denominato package.json. Puoi utilizzare npm, yarn, pnpm, o Bun per installare le dipendenze Node.js.

Il framework di Functions per Node.js è una dipendenza obbligatoria per tutte le funzioni. Sebbene Cloud Run Functions lo installi per tuo conto al momento della creazione della funzione, ti consigliamo di includerlo come dipendenza esplicita per maggiore chiarezza.

Se la tua funzione si basa su dipendenze private, ti consigliamo di eseguire il mirroring di functions-framework nel tuo registro privato. Includi functions-framework sottoposto a mirroring come dipendenza della tua funzione per evitare di installare il pacchetto dalla rete internet pubblica.

Per specificare una dipendenza per la tua funzione, aggiungila al file package.json.

Se il buildpack Node.js rileva un file di blocco, ad esempio package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lock, o bun.lockb all'interno del progetto, assegna la priorità a questo file di blocco quando installi le dipendenze utilizzando npm ci, yarn install, pnpm install, o bun install.

Nell'esempio seguente è elencata una dipendenza nel file package.json:

{
  "dependencies": {
    "escape-html": "^1.0.3"
  }
}

Cloud Run importa la dipendenza nella funzione:

const functions = require('@google-cloud/functions-framework');
const escapeHtml = require('escape-html');

/**
 * Responds to an HTTP request using data from the request body parsed according
 * to the "content-type" header.
 *
 * @param {Object} req Cloud Function request context.
 * @param {Object} res Cloud Function response context.
 */
functions.http('helloHttp', (req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || 'World')}!`);
});

Utilizzare npm per installare localmente i moduli Node.js

Il modo più semplice per installare un modulo Node.js localmente è utilizzare il comando npm install nella cartella contenente la funzione Cloud Run. Ad esempio, il comando seguente aggiunge il modulo uuid:

npm install uuid

Questa operazione combina due passaggi:

1. Contrassegna l'ultima versione del modulo come dipendenza nel file package.json. Questo è molto importante: Cloud Run Functions installa solo i moduli dichiarati nel file package.json.
2. Scarica il modulo nella directory node_modules. Questo ti consente di utilizzare il modulo durante lo sviluppo locale.

Se non hai installato npm sulla tua macchina, scarica npm.

Nota: sono disponibili pacchetti npm per una serie di Google Cloud prodotti. Consulta Librerie client di Node.js.

Configurare le dipendenze del deployment

Puoi installare le dipendenze di produzione per NPM, Yarn o Pnpm:

Gestore di pacchetti NPM

Quando esegui il deployment della funzione, Cloud Run Functions installa le dipendenze dichiarate nel file package.json utilizzando il npm install comando:

npm install --production

Gestore di pacchetti Yarn

Nel runtime Node.js 8 e versioni successive, se esiste un file yarn.lock, Cloud Run Functions utilizza invece il yarn install comando:

yarn install --production

Gestore di pacchetti Pnpm

Nel runtime Node.js 8 e versioni successive, se esiste un file pnpm-lock.yaml, Cloud Run Functions utilizza invece il pnpm install comando:

pnpm install

Gestore di pacchetti Bun

Il buildpack Node.js supporta il gestore di pacchetti Bun. Con il gestore di pacchetti Bun, puoi installare le dipendenze mantenendo la struttura del progetto Node.js e la versione del runtime esistenti. Puoi scegliere uno dei seguenti meccanismi per installare le dipendenze utilizzando Bun:

• Rilevamento automatico: il buildpack Node.js rileva il gestore di pacchetti Bun quando includi un file bun.lock o bun.lockb nel progetto. Per configurare il rilevamento automatico con Bun, segui questi passaggi:

  1. Crea il file di blocco:

     bun install --lockfile-only
     

  2. Esegui il deployment in Cloud Run eseguendo il seguente comando:

      gcloud run deploy --source . --base-image=nodejs24
     

• Consenso esplicito: imposta la variabile di ambiente GOOGLE_PACKAGE_MANAGER su bun. Con questo metodo, non devi creare e gestire i file di blocco. Esegui il seguente comando per eseguire il deployment in Cloud Run:

  gcloud run deploy --source . --base-image=nodejs24 --set-build-env-vars GOOGLE_PACKAGE_MANAGER=bun
  

Sebbene il buildpack utilizzi Bun per l'installazione delle dipendenze, il runtime Node.js esegue comunque l'applicazione. Il progetto deve includere un file package.json. Per maggiori dettagli sui requisiti di configurazione, consulta Creazione di un'applicazione Node.js nella documentazione di Buildpacks.

Esecuzione di passaggi di build personalizzati durante il deployment

Dopo il deployment, puoi eseguire un passaggio di build personalizzato durante il processo di compilazione della funzione aggiungendo uno script gcp-build nel file package.json.

Quando viene eseguito questo script, sono disponibili le dipendenze nei campi dependencies e devDependencies del file package.json. Dopo l'esecuzione del passaggio di build personalizzato, Cloud Run Functions rimuove e rigenera la cartella node_modules installando solo le dipendenze di produzione dichiarate nel campo dependencies del file package.json.

Se non è presente alcuno script gcp-build in package.json, Cloud Run Functions installa solo le dipendenze di produzione.

Utilizzo dei pacchetti di sistema

Il runtime Node.js include anche una serie di pacchetti di sistema nell'ambiente di esecuzione.

Inclusione di moduli Node.js locali

Puoi anche includere moduli Node.js locali come parte della funzione. Puoi ottenere questo risultato dichiarando il modulo in package.json utilizzando il prefisso file:. Nell'esempio seguente, mymodule si riferisce al nome del modulo e mymoduledir è la directory contenente il modulo:

  {
  "dependencies": {
    "mymodule": "file:mymoduledir"
  }
}

Il codice di questo modulo locale deve essere archiviato in una posizione diversa dalla cartella node_modules all'interno della directory root della funzione.

Nota: se esegui il deployment utilizzando lo strumento a riga di comando gcloud, gcloud crea automaticamente un file .gcloudignore nella directory della funzione. Per impostazione predefinita, la cartella node_modules viene aggiunta a questo file .gcloudignore e non viene caricata durante il deployment. Non è necessario includere la cartella node_modules quando carichi manualmente il codice come file zip. Puoi eseguire il deployment della funzione senza la cartella node_modules.

Caricamento dei moduli Node.js

Utilizza la funzione Node.js require() per caricare qualsiasi modulo Node.js installato. Puoi anche utilizzare la funzione require() per importare i file locali di cui esegui il deployment insieme alla funzione.

Utilizzo di moduli privati

Puoi utilizzare un modulo npm privato fornendo le impostazioni per l'autenticazione con il registro in un file .npmrc nella directory della funzione. Se utilizzi Yarn v2 o versioni successive come gestore di pacchetti, questo file è denominato .yarnrc.yml.

Moduli privati di Artifact Registry

Un repository di pacchetti Node.js di Artifact Registry può ospitare moduli privati per la tua funzione. Quando esegui il deployment di una funzione Cloud Run Functions, il processo di compilazione genera automaticamente le credenziali Artifact Registry per il service account Cloud Build. Devi solo elencare il repository Artifact Registry in .npmrc senza generare credenziali aggiuntive. Ad esempio:

@SCOPE:registry=https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
//REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME:always-auth=true

Questo approccio funziona anche per il gestore di pacchetti Yarn v1. Se utilizzi Yarn v2 o versioni successive, devi solo elencare il repository Artifact Registry in .yarnrc.yml senza credenziali aggiuntive. Ad esempio:

npmScopes:
  SCOPE:
    npmRegistryServer: https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
    npmAlwaysAuth: true

Moduli privati di altri repository

La documentazione di npm spiega come creare token di accesso di sola lettura personalizzati. Sconsigliamo l'utilizzo del file .npmrc creato nella directory home perché contiene un token di lettura/scrittura. Le autorizzazioni in scrittura non sono richieste durante il deployment e potrebbero rappresentare un rischio per la sicurezza.

Non includere il file .npmrc se non utilizzi repository privati, in quanto può aumentare il tempo di deployment delle tue funzioni.

Nota: se utilizzi autorizzazioni personalizzate (ad esempio quelle necessarie per VPC), assicurati di consentire esplicitamente alle tue funzioni di accedere al repository privato di destinazione.

Formato file

Se utilizzi un file .npmrc per impostare un token di autenticazione personalizzato, deve includere la seguente riga.

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

Sostituisci:

• REGISTRY_DOMAIN: il nome di dominio del tuo registro npm privato. Se il tuo repository è ospitato su npmjs.org, imposta questo campo su registry.npmjs.org.

• AUTH_TOKEN: il token di autorizzazione per il tuo registro npm. Può trattarsi del valore di testo letterale del token o della stringa di testo ${NPM_TOKEN}, che npm sostituisce con il valore effettivo del token dell'ambiente.

  Puoi impostare la variabile di ambiente $NPM_TOKEN con l'argomento --set-build-env-vars sul tuo comando gcloud functions deploy. Per maggiori dettagli sul token di autenticazione NPM, consulta il tutorial NPM sui moduli privati.

Creare la funzione con le dipendenze copiate

Le dipendenze copiate sono quelle la cui origine è inclusa direttamente nel pacchetto di codice sorgente e ricompilata insieme al tuo codice. Crea dipendenze copiate Node.js e salta l'installazione durante il deployment utilizzando la variabile di ambiente di build GOOGLE_VENDOR_NPM_DEPENDENCIES.

Prerequisiti per le dipendenze copiate

1. Assicurati di avere una funzione operativa con tutte le dipendenze che vuoi copiare nel file package.json.

2. Installa queste dipendenze localmente eseguendo:

       npm install
   

3. Rimuovi node_modules dal file .gcloudignore nella directory di lavoro.

4. Esegui il deployment della funzione, assicurandoti che la versione locale di Node.js sia la stessa di quella specificata durante il deployment.

5. Esegui il deployment della funzione e delle dipendenze copiate con il seguente comando:

     gcloud run deploy SERVICE \
       --source . \
       --function FUNCTION_ENTRY_POINT \
       --set-build-env-vars GOOGLE_VENDOR_NPM_DEPENDENCIES=true
   

   Sostituisci:

   • SERVICE: il nome della funzione Cloud Run di cui stai eseguendo il deployment
   • FUNCTION_ENTRY_POINT: con l'entry point della tua funzione nel codice sorgente.

Se specifichi un motore npm nel file package.json, la versione specificata di npm viene scaricata al tempo di compilazione. Per disattivare questo comportamento, rimuovilo dal file package.json.