Il runtime Node.js

Il runtime Node.js è lo stack software responsabile dell'installazione del codice dell'applicazione e delle dipendenze e dell'esecuzione dell'applicazione nell'ambiente flessibile.

• Le versioni 18 e successive sono basate su buildpacks, che richiede la scelta di un sistema operativo nel file app.yaml. Ad esempio, per utilizzare Node.js 22 (anteprima), devi specificare Ubuntu 22 come sistema operativo.

• Le versioni 16 e precedenti sono state create utilizzando Docker.

• Il motore Node.js predefinito utilizza la release LTS più recente.

Per l'elenco completo delle versioni di Node.js supportate e delle versioni di Ubuntu corrispondenti, consulta la pianificazione del supporto per l'esecuzione.

Gestione pacchetti

Durante il deployment, il runtime utilizza il gestore di pacchetti npm, yarn o Pnpm per installare le dipendenze e avviare l'applicazione. Il gestore di pacchetti viene impostato con la logica seguente:

• Il gestore di pacchetti predefinito è npm.
• Se nella directory principale dell'applicazione è presente un file yarn.lock, il runtime utilizza il gestore di pacchetti yarn.
• Solo per Node.js 18 e versioni successive, se è presente un file pnpm-lock.yaml nella directory principale dell'applicazione, il runtime utilizza il gestore di pacchetti Pnpm.
• Se esistono entrambi i valori package-lock.json, yarn.lock o pnpm-lock.yaml, il deployment non andrà a buon fine e verrà visualizzato un errore. Se ti serve il file package-lock.json, devi specificare gli altri file del gestore di pacchetti nella sezione skip_files del file app.yaml per decidere quale gestore di pacchetti utilizzare.

Scegli una versione Node.js

Nuove versioni di runtime

Per il runtime Node.js versione 18 e successive, devi includere le impostazioni runtime_config e operating_system nel file app.yaml per specificare un sistema operativo.

Per utilizzare i nuovi runtime, devi installare gcloud CLI versione 420.0.0 o successiva. Puoi aggiornare gli strumenti dell'interfaccia a riga di comando eseguendo il comando gcloud components update. Per visualizzare la versione installata, puoi eseguire il comando gcloud version.

Facoltativamente, specifica una versione tramite:

• Aggiunta dell'impostazione runtime_version al file app.yaml in corso... Per impostazione predefinita, viene utilizzata la versione più recente di Node.js se l'impostazione runtime_version non è specificata. Ad esempio:

  • Per specificare Node.js 22 (anteprima) su Ubuntu 22:

    runtime: nodejs
    env: flex
  
    runtime_config:
        operating_system: "ubuntu22"
        runtime_version: "22"
  

  • Per specificare l'ultima versione supportata di Node.js su Ubuntu 22:

    runtime: nodejs
    env: flex
  
    runtime_config:
        operating_system: "ubuntu22"
  

• Includere qualsiasi versione Node.js nel file package.json dell'applicazione utilizzando il campo engines. Tieni presente che, quando utilizzi il campo engines per specificare una versione, l'impostazione runtime_version ha la precedenza. Per evitare interruzioni impreviste, ti consigliamo di specificare una versione Node.js nel campo engines. Ad esempio:

    {
      "engines": {
        "node": "22.x"
      }
    }
  

  La proprietà engines.node può essere un intervallo del separatore. Se lo specifichi, il runtime scarica e installa la versione più recente di Node.js che corrisponde all'intervallo di server. Se non viene trovata alcuna corrispondenza, il deployment dell'applicazione non andrà a buon fine e il runtime restituirà un messaggio di errore.

Versioni di runtime precedenti

Per il runtime Node.js versione 16 e precedenti, specifica una versione nel file package.json della tua applicazione utilizzando il campo engines.

L'esempio seguente configura il runtime in modo che utilizzi la release più recente di Node 9.

{
  "engines": {
    "node": "9.x"
  }
}

La proprietà engines.node può essere un intervallo del separatore. Se lo specifichi, il runtime scarica e installa la versione più recente di Node.js che corrisponde all'intervallo di server. Se non viene trovata alcuna corrispondenza, il deployment dell'applicazione non andrà a buon fine e il runtime restituirà un messaggio di errore.

Versione Gestione pacchetti

L'immagine di runtime mira a utilizzare l'ultima release di yarn e la release di npm, disponibili nell'ultima release Node.js LTS.

Puoi specificare una versione diversa del gestore di pacchetti da utilizzare nel file package.json della tua applicazione utilizzando il campo engines. In questo caso, il runtime assicura che il gestore di pacchetti utilizzato per il deployment abbia una versione corrispondente alla specifica indicata nel campo engines.

Se viene fornita una specifica della versione sia yarn che npm, solo il gestore di pacchetti utilizzato per il deployment verrà aggiornato, se necessario. Ciò consente di risparmiare tempo durante il deployment perché non installa una versione personalizzata di un gestore di pacchetti se non viene effettivamente utilizzato per eseguire il deployment dell'applicazione.

L'esempio seguente configura il runtime in modo da utilizzare una versione personalizzata di npm:

{
  "engines": {
    "npm": "5.x"
  }
}

Nell'esempio successivo viene configurato il runtime in modo che utilizzi una versione personalizzata di yarn:

{
  "engines": {
    "yarn": ">=1.0.0 <2.0.0"
  }
}

Le proprietà engines.npm e engines.yarn possono essere entrambe un intervallo di dati.

Dipendenze

Durante il deployment, il runtime utilizza il gestore di pacchetti npm o yarn per installare le dipendenze eseguendo npm install o yarn install. Consulta la sezione Gestione pacchetti per ulteriori informazioni su come il runtime seleziona il gestore di pacchetti da utilizzare.

Inoltre, per ulteriori informazioni sulla gestione dei pacchetti Node.js in Google App Engine, consulta Utilizzo delle librerie Node.js.

Per abilitare l'utilizzo dei pacchetti Node.js che richiedono estensioni native, i seguenti pacchetti Ubuntu sono preinstallati nell'immagine Docker.

• build-essential
• ca-certificates
• curl
• git
• imagemagick
• libkrb5-dev
• netbase
• python

Se la tua applicazione richiede ulteriori dipendenze a livello di sistema operativo, dovrai utilizzare un runtime personalizzato basato su questo runtime per installare i pacchetti appropriati.

Script di build di Gestione dei partner di rete

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

Per impedire alla build di eseguire lo script npm run build, devi:

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

• Aggiungi la variabile di ambiente di build GOOGLE_NODE_RUN_SCRIPTS con un valore vuoto nel file app.yaml.

  build_env_variables:
    GOOGLE_NODE_RUN_SCRIPTS: ''
  

Per dettagli su come specificare le variabili di ambiente di build, consulta la sezione build_env_variables nel file app.yaml.

Avvio dell'applicazione

Il runtime avvia l'applicazione utilizzando npm start, che utilizza il comando specificato in package.json. Ad esempio:

"scripts": {
  "start": "node app.js"
}

Lo script iniziale deve avviare un server web che risponda alle richieste HTTP sulla porta specificata dalla variabile di ambiente PORT, in genere 8080.

Estendere il runtime

Puoi utilizzare runtime personalizzati per aggiungere ulteriori funzionalità a un'app Node.js in esecuzione nell'ambiente flessibile di App Engine. Per configurare un runtime personalizzato, sostituisci la seguente riga nel file app.yaml:

runtime: nodejs

con questa riga:

runtime: custom

Devi anche aggiungere i file Dockerfile e .dockerignore nella stessa directory che contiene il file app.yaml.

Consulta la documentazione sui runtime personalizzati per scoprire come definire un Dockerfile in un runtime personalizzato.

HTTPS e proxy di inoltro

App Engine termina la connessione HTTPS al bilanciatore del carico e inoltra la richiesta alla tua applicazione. Alcune applicazioni devono determinare l'IP e il protocollo della richiesta originale. L'indirizzo IP dell'utente è disponibile nell'intestazione X-Forwarded-For standard. Le applicazioni che richiedono queste informazioni devono configurare il framework web in modo da considerare attendibile il proxy.

Con Express.js, utilizza l'impostazione trust proxy:

app.set('trust proxy', true);

Per informazioni sull'applicazione delle connessioni HTTPS, consulta Modalità di gestione delle richieste.

Variabili di ambiente

Le seguenti variabili di ambiente sono impostate dall'ambiente di runtime:

Variabile di ambiente	Descrizione
GAE_INSTANCE	Il nome dell'istanza corrente.
GAE_MEMORY_MB	La quantità di memoria disponibile per il processo di applicazione.
GAE_SERVICE	Il nome del servizio specificato nel file app.yaml della tua applicazione oppure, se non viene specificato alcun nome, il nome viene impostato su default.
GAE_VERSION	L'etichetta della versione dell'applicazione corrente.
GOOGLE_CLOUD_PROJECT	L'ID progetto associato all'applicazione, visibile nella console Google Cloud
NODE_ENV	Quando viene eseguito il deployment dell'app, il valore è production.
PORT	La porta che riceverà le richieste HTTP. Impostato su 8080.

Puoi impostare variabili di ambiente aggiuntive con app.yaml.

Server metadati

Ogni istanza dell'applicazione può utilizzare il server di metadati di Compute Engine per eseguire query sull'istanza, tra cui nome host, indirizzo IP esterno, ID istanza, metadati personalizzati e informazioni sull'account di servizio. App Engine non consente di impostare metadati personalizzati per ogni istanza, ma puoi impostare metadati personalizzati a livello di progetto e leggerli dalle istanze di App Engine e Compute Engine.

Questa funzione di esempio utilizza il server di metadati per ottenere l'indirizzo IP esterno dell'istanza per la versione 16 e precedenti del runtime Node.js e la versione 18 e successive. Tieni presente che devi aggiornare app.yaml per utilizzare la nuova versione. Per saperne di più sull'utilizzo delle versioni più recenti, consulta runtime Node.js.

const express = require('express');
const fetch = require('node-fetch');

const app = express();
app.enable('trust proxy');

const METADATA_NETWORK_INTERFACE_URL =
  'http://metadata/computeMetadata/v1/' +
  '/instance/network-interfaces/0/access-configs/0/external-ip';

const getExternalIp = async () => {
  const options = {
    headers: {
      'Metadata-Flavor': 'Google',
    },
    json: true,
  };

  try {
    const response = await fetch(METADATA_NETWORK_INTERFACE_URL, options);
    const ip = await response.json();
    return ip;
  } catch (err) {
    console.log('Error while talking to metadata server, assuming localhost');
    return 'localhost';
  }
};

app.get('/', async (req, res, next) => {
  try {
    const externalIp = await getExternalIp();
    res.status(200).send(`External IP: ${externalIp}`).end();
  } catch (err) {
    next(err);
  }
});

const PORT = parseInt(process.env.PORT) || 8080;
app.listen(PORT, () => {
  console.log(`App listening on port ${PORT}`);
  console.log('Press Ctrl+C to quit.');
});