Il runtime Node.js

La funzione Cloud Run viene eseguita in un ambiente costituito da una versione del sistema operativo con pacchetti aggiuntivi, supporto della lingua e la libreria Node.js Functions Framework che supporta e richiama la funzione. Questo ambiente è identificato dalla versione della lingua ed è noto come ID runtime.

Preparazione della funzione

Puoi preparare una funzione direttamente dalla console Google Cloud o scriverla sulla tua macchina locale e caricarla. Per preparare la tua macchina locale per lo sviluppo Node.js, consulta Configurare un ambiente di sviluppo Node.js.

Runtime e immagini di base Node.js supportati

Runtime ID runtime Serie Immagine di base del runtime
Node.js 22 nodejs22
  • google-22 (valore predefinito)
  • google-22-full
    		•
  • google-22/nodejs22
  • google-22-full/nodejs22
    		•
    Node.js 20 nodejs20
  • google-22 (valore predefinito)
  • google-22-full
    		•
  • google-22/nodejs20
  • google-22-full/nodejs20
    		•
    Node.js 18 nodejs18
  • google-22 (valore predefinito)
  • google-22-full
    		•
  • google-22/nodejs18
  • google-22-full/nodejs18
    		•
    Node.js 16 nodejs16 google-18-full google-18-full/nodejs16
    Node.js 14 nodejs14 google-18-full google-18-full/nodejs14
    Node.js 12 nodejs12 google-18-full google-18-full/nodejs12
    Node.js 10 nodejs10 google-18-full google-18-full/nodejs10
    Node.js 8 nodejs8 Dismesso Dismesso
    Node.js 6 nodejs6 Dismesso Dismesso

    Seleziona il runtime

    Puoi selezionare uno dei runtime Node.js supportati per la tua funzione durante il deployment.

    Puoi selezionare una versione di runtime utilizzando la console Google Cloud o gcloud CLI. Fai clic sulla scheda per leggere le istruzioni sull'utilizzo dello strumento scelto:

    gcloud

    Specifica l'immagine di base Node.js per la tua funzione utilizzando il flag --base-image, durante il deployment della funzione. Ad esempio:

    gcloud beta run deploy FUNCTION \
    --source . \
    --function FUNCTION_ENTRYPOINT \
    --base-image nodejs22

    Sostituisci:

    • FUNCTION con il nome della funzione di cui stai eseguendo il deployment. Puoi omettere del tutto questo parametro, ma se lo fai ti verrà chiesto il nome.

    • FUNCTION_ENTRYPOINT con il punto di ingresso della funzione nel codice sorgente. Questo è il codice che Cloud Run esegue quando viene eseguita la funzione. Il valore di questo flag deve essere un nome di funzione o un nome di classe completamente qualificato esistente nel codice sorgente.

    Per istruzioni dettagliate sul deployment di una funzione utilizzando l'interfaccia a riga di comando gcloud, consulta Eseguire il deployment di funzioni in Cloud Run.

    Console

    Puoi selezionare una versione del runtime quando crei o aggiorni una funzione Cloud Run nella console Google Cloud. Per istruzioni dettagliate sul deployment di una funzione, consulta Eseguire il deployment di funzioni in Cloud Run.

    Per selezionare un runtime nella console Google Cloud quando crei una funzione:

    1. Nella console Google Cloud, vai alla pagina Cloud Run:

      Vai a Cloud Run

    2. Fai clic su Scrivi una funzione.

    3. Nell'elenco Runtime, seleziona una versione del runtime Node.js.

    4. Fai clic su Crea e attendi che Cloud Run crei il servizio utilizzando una revisione segnaposto.

    5. La console ti reindirizzerà alla scheda Origine, dove potrai visualizzare il codice sorgente della funzione. Fai clic su Salva e ridistribuisci.

    Per istruzioni dettagliate su come aggiornare la versione del runtime dopo il deployment della funzione, consulta Eseguire nuovamente il deployment del nuovo codice sorgente.

    Struttura del codice sorgente

    Affinché le funzioni Cloud Run trovino la definizione della funzione, il codice sorgente deve seguire una struttura specifica. Per ulteriori informazioni, consulta Scrivere funzioni Cloud Run.

    Specifica delle dipendenze

    Puoi specificare le dipendenze per le funzioni elencandole in un file package.json. Per ulteriori informazioni, consulta Specificare le dipendenze in Node.js.

    Script di build NPM

    Per impostazione predefinita, il runtime di Node.js esegue npm run build se viene rilevato uno script build in package.json. Se hai bisogno di un maggiore controllo sui passaggi di compilazione prima di avviare l'applicazione, puoi fornire un passaggio di compilazione personalizzato aggiungendo uno script gcp-build al file package.json.

    Puoi impedire alla build di eseguire lo script npm run build in uno dei seguenti modi:

    • Aggiunta di uno script gcp-build con un valore vuoto nel file package.json: "gcp-build":"".

    • Impostare la variabile di ambiente di compilazione GOOGLE_NODE_RUN_SCRIPTS sulla stringa vuota per impedire l'esecuzione di tutti gli script.

    Completamento della funzione asincrona

    Quando utilizzi attività asincrone che richiedono callback o oggetti Promise, devi informare esplicitamente il runtime del completamento dell'esecuzione di queste attività da parte della funzione. Puoi farlo in diversi modi, come mostrato nei seguenti esempi. L'aspetto fondamentale è che il codice deve attendere il completamento della tâche asincrona o di Promise prima di restituire il valore; in caso contrario, il componente asincrono della funzione potrebbe essere interrotto prima del completamento.

    Funzioni basate su eventi

    Valore restituito implicito

      exports.implicitlyReturning = async (event, context) => {
    return await asyncFunctionThatReturnsAPromise();
  };

    Ritorno esplicito

      exports.explicitlyReturning = function (event, context) {
    return asyncFunctionThatReturnsAPromise();
  };

    Funzioni HTTP

    // OK: await-ing a Promise before sending an HTTP response
await Promise.resolve();

// WRONG: HTTP functions should send an
// HTTP response instead of returning.
return Promise.resolve();

// HTTP functions should signal termination by returning an HTTP response.
// This should not be done until all background tasks are complete.
res.send(200);
res.end();

// WRONG: this may not execute since an
// HTTP response has already been sent.
return Promise.resolve();

    Utilizzare il middleware per gestire le richieste HTTP

    Le funzioni HTTP di Node.js forniscono oggetti request e response compatibili con ExpressJS per semplificare l'utilizzo delle richieste HTTP. Le funzioni Cloud Run legge automaticamente il corpo della richiesta, pertanto riceverai sempre il corpo di una richiesta indipendentemente dal tipo di media. Ciò significa che le richieste HTTP devono essere considerate completamente lette al momento dell'esecuzione del codice. L'annidamento delle app ExpressJS deve essere utilizzato con questo avvertimento: in particolare, il middleware che si aspetta che il corpo di una richiesta non sia letto potrebbe non comportarsi come previsto.

    Utilizzare i moduli ES

    I moduli ECMAScript (moduli ES o ESM) sono una funzionalità non segnalata standard del TC39 in Node versione 14 e successive per il caricamento dei moduli JavaScript. A differenza di CommonJS, ESM fornisce un'API asincrona per il caricamento dei moduli. Fornisce inoltre un miglioramento della sintassi popolare con le istruzioni import e export che possono essere utilizzate all'interno di una funzione Cloud Run (anziché le istruzioni require).

    Per utilizzare ESM all'interno di una funzione Cloud Run, devi dichiarare "type": "module" all'interno di package.json.

    {
  ...
  "type": "module",
  ...
}

    Dopodiché puoi utilizzare le istruzioni import e export.

    Scopri di più sull'utilizzo dei moduli ES.