Il runtime Node.js è lo stack software responsabile dell'installazione del codice e delle dipendenze dell'applicazione e della successiva esecuzione di tale applicazione nell'ambiente flessibile.
La versione
18
e successive sono create utilizzando buildpacks, che richiede la scelta di un sistema operativo nel fileapp.yaml
. Ad esempio, per utilizzare Node.js 20, devi specificare Ubuntu 22 come sistema operativo.La versione
16
e le versioni 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 della versione di Ubuntu corrispondente, consulta la pianificazione del supporto dell'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 seguente logica:
- Il gestore di pacchetti predefinito è
npm
. - Se nella directory principale dell'applicazione è presente un file
yarn.lock
, il runtime utilizza il gestore di pacchettiyarn
. - Solo per i runtime Node.js versione 18 e 20, se è presente un file
pnpm-lock.yaml
nella directory principale dell'applicazione, il runtime utilizza il gestore di pacchettiPnpm
. - Se esistono entrambi i valori
package-lock.json
,yarn.lock
opnpm-lock.yaml
, il deployment non andrà a buon fine e verrà generato un errore. Se ti serve il filepackage-lock.json
, devi specificare gli altri file del gestore di pacchetti nella sezioneskip_files
del fileapp.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 nel seguente modo:
Aggiunta dell'impostazione
runtime_version
nel fileapp.yaml
. Per impostazione predefinita, viene utilizzata la versione Node.js più recente se l'impostazioneruntime_version
non è specificata. Ad esempio:- Per specificare Node.js 20 su Ubuntu 22:
runtime: nodejs env: flex runtime_config: operating_system: "ubuntu22" runtime_version: "20"
- Per specificare l'ultima versione di Node.js supportata 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 campoengines
. Tieni presente che quando utilizzi il campoengines
per specificare una versione, l'impostazioneruntime_version
ha la precedenza. Per evitare interruzioni impreviste, ti consigliamo di specificare una versione Node.js nel campoengines
. Ad esempio:{ "engines": { "node": "20.x" } }
La proprietà
engines.node
può essere un intervallo server. Se lo specifichi, il runtime scarica e installa l'ultima versione 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 di Node 9 più recente.
{
"engines": {
"node": "9.x"
}
}
La proprietà engines.node
può essere un intervallo server. Se lo specifichi, il runtime scarica e installa l'ultima versione 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 gestore pacchetti
L'immagine di runtime mira a utilizzare l'ultima release di yarn
e la release di npm
, disponibile nell'ultima release di 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 vengono fornite entrambe le specifiche della versione yarn
e npm
, se necessario verrà aggiornato solo il gestore di pacchetti utilizzato per il deployment. Ciò consente di risparmiare tempo perché non installa una versione personalizzata di un gestore di pacchetti che non viene effettivamente utilizzata per eseguire 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 successivo 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 misura.
Dipendenze
Durante il deployment, il runtime utilizzerà 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 consentire l'utilizzo 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 NPM
Per il runtime Node.js versione 18 e successive, l'ambiente di runtime viene eseguito
npm run build
se viene rilevato uno script build
in package.json
per impostazione predefinita. Se hai bisogno di un controllo aggiuntivo sui passaggi di compilazione prima di avviare l'applicazione, puoi fornire un passaggio di build personalizzato aggiungendo uno script gcp-build
al 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 build
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 impiega 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 tuo file app.yaml
:
runtime: nodejs
con questa riga:
runtime: custom
Devi inoltre 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 forwarding
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 originali. L'indirizzo IP dell'utente è disponibile nell'intestazione X-Forwarded-For
standard. Le applicazioni che richiedono queste informazioni devono configurare il proprio framework web in modo che il proxy venga considerato attendibile.
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 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 è specificato alcun nome del servizio, è 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 dei metadati
Ogni istanza della tua applicazione può utilizzare il server di metadati di Compute Engine per eseguire query su informazioni sull'istanza, inclusi 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 è possibile 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 il runtime Node.js 16 e versioni precedenti e la versione 18 e successive. Tieni presente che
devi aggiornare app.yaml
per utilizzare la nuova versione. Consulta Runtime Node.js per ulteriori informazioni sull'utilizzo di versioni più recenti.