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.
Versioni Node.js
Node.js 22 (anteprima) utilizza buildpacks. Il motore Node.js predefinito utilizza la release LTS più recente. Per l'elenco completo delle versioni di Node.js supportate e della versione Ubuntu corrispondente, consulta la pianificazione del supporto di runtime.
Per utilizzare una versione Node.js supportata, devi:
Installa
gcloud CLI
versione 420.0.0 o successiva. Puoi aggiornare gli strumenti dell'interfaccia a riga di comando eseguendo il comandogcloud components update
. Per visualizzare la versione installata, esegui il comandogcloud version
.Includi le impostazioni
runtime_config
eoperating_system
nel fileapp.yaml
per specificare un sistema operativo.Facoltativamente, puoi specificare una versione tramite:
Aggiunta dell'impostazione
runtime_version
nel fileapp.yaml
. Per impostazione predefinita, viene utilizzata l'ultima versione di Node.js se l'impostazioneruntime_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 di Node.js supportata su Ubuntu 22:
runtime: nodejs env: flex runtime_config: operating_system: "ubuntu22"
Includere l'ultima versione di Node.js supportata nel file
package.json
della tua applicazione utilizzando il campoengines
. Quando utilizzi il campoengines
per specificare una versione, l'impostazioneruntime_version
ha la precedenza. Per evitare interruzioni impreviste, ti consigliamo di specificare una versione di Node.js nel campoengines
. Ad esempio:{ "engines": { "node": "22.x" } }
La proprietà
engines.node
può essere un intervallo di servizio. Se specifichi questa proprietà, il runtime scarica e installa la versione più recente di Node.js che corrisponde all'intervallo di semver. Se non viene trovata alcuna corrispondenza, il deployment dell'applicazione non riesce e il runtime restituisce un errore.
Versioni precedenti del runtime
Per la versione 16 e precedenti del runtime Node.js, specifica una versione nel
file package.json
dell'applicazione utilizzando il campo engines
.
L'esempio seguente configura il runtime per utilizzare la release Node 9:
{
"engines": {
"node": "9.x"
}
}
La proprietà engines.node
può essere un intervallo di servizio.
Se specifichi questa proprietà, il runtime scarica e installa la versione più recente di
Node.js che corrisponde all'intervallo di semver. Se non viene trovata alcuna corrispondenza, il deployment dell'applicazione non riesce e il runtime restituisce un messaggio di errore.
Supporto per altri runtime Node.js
Se devi utilizzare una versione Node.js non supportata, puoi creare un runtime personalizzato e selezionare un'immagine di base valida con la versione Node.js che ti serve.
Per le immagini di base fornite da Google o le immagini di base Docker Node.js, consulta Creazione di runtime personalizzati.
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 è impostato con la seguente logica:
- Il gestore di pacchetti predefinito è
npm
. - Se nella directory root dell'applicazione è presente un file
yarn.lock
, il runtime utilizza il gestore di pacchettiyarn
. - Solo per Node.js versione 18 e successive, se è presente un file
pnpm-lock.yaml
nella directory principale dell'applicazione, il runtime utilizza invece il gestore di pacchettiPnpm
. - Se esistono sia
package-lock.json
siayarn.lock
opnpm-lock.yaml
, il deployment non riuscirà e verrà generato un errore. Se hai bisogno del filepackage-lock.json
, devi specificare gli altri file del gestore di pacchetti nella sezioneskip_files
del fileapp.yaml
per risolvere il gestore di pacchetti da utilizzare.
Versione del gestore di pacchetti
L'immagine di runtime mira a utilizzare l'ultima release yarn
e la release di
npm
disponibile nella release Node.js LTS più recente.
Puoi specificare una versione del gestore di pacchetti diversa da utilizzare nel file package.json
della tua applicazione utilizzando il campo engines
. In questo caso, il runtime garantisce che la versione del gestore di pacchetti utilizzato per il deployment corrisponda alle specifiche elencate nel campo engines
.
Se vengono fornite sia le specifiche della versione yarn
sia npm
, se necessario verrà aggiornato solo il gestore di pacchetti utilizzato per il deployment. Ciò consente di risparmiare tempo in quanto il deployment non richiede l'installazione di una versione personalizzata
di un gestore di pacchetti che non viene effettivamente utilizzato per il deployment
dell'applicazione.
L'esempio seguente configura il runtime in modo che utilizzi una versione personalizzata di npm
:
{
"engines": {
"npm": "5.x"
}
}
L'esempio seguente configura 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 servizio.
Dipendenze
Durante il deployment, il runtime utilizzerà il gestore di pacchetti npm o yarn per installare le dipendenze eseguendo npm install
o yarn install
. Per ulteriori informazioni su come il runtime seleziona il gestore di pacchetti da utilizzare, consulta la sezione Gestione pacchetti.
Inoltre, per ulteriori informazioni sulla gestione dei pacchetti Node.js su Google App Engine, consulta Utilizzo delle librerie Node.js.
Per abilitare l'uso di 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, per installare i pacchetti appropriati dovrai utilizzare un runtime personalizzato basato su questo runtime.
Script di build Gestione dei partner di rete
Per la versione 18 e successive del runtime Node.js, 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 ulteriore 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 filepackage.json
:"gcp-build":""
. Aggiungi la variabile di ambiente di compilazione
GOOGLE_NODE_RUN_SCRIPTS
con un valore vuoto nel fileapp.yaml
.build_env_variables: GOOGLE_NODE_RUN_SCRIPTS: ''
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 di avvio dovrebbe avviare un server web che risponde alle richieste HTTP sulla porta specificata dalla variabile di ambiente PORT
, in genere 8080.
Estensione del 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.
Proxy HTTPS e di forwarding
App Engine termina la connessione HTTPS al bilanciatore del carico e inoltra la richiesta all'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 per 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
L'ambiente di runtime imposta le seguenti variabili di ambiente:
Variabile di ambiente | Descrizione |
---|---|
GAE_INSTANCE |
Il nome dell'istanza attuale. |
GAE_MEMORY_MB |
La quantità di memoria disponibile per il processo di richiesta. |
GAE_SERVICE |
Il nome del servizio specificato nel file app.yaml dell'applicazione oppure, se non viene specificato alcun nome di servizio, è impostato su default .
|
GAE_VERSION |
L'etichetta della versione dell'applicazione corrente. |
GOOGLE_CLOUD_PROJECT |
L'ID progetto associato alla tua applicazione, visibile nella console Google Cloud |
NODE_ENV |
Dopo il deployment dell'app, il valore è production . |
PORT |
La porta che riceverà le richieste HTTP. Impostata su 8080 .
|
Puoi impostare altre variabili di ambiente con app.yaml
.
Server metadati
Ogni istanza della tua applicazione può utilizzare il server di metadati di Compute Engine per eseguire query sulle informazioni sull'istanza, tra cui nome host, indirizzo IP esterno, ID istanza, metadati personalizzati e informazioni dell'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.