Ambiente di runtime Node.js

Il runtime Node.js è lo stack software responsabile dell'installazione del codice e delle sue dipendenze del servizio web e delle sue dipendenze e dell'esecuzione del servizio.

Il runtime Node.js per App Engine nell'ambiente standard è dichiarato nel file app.yaml:

runtime: nodejsVERSION

Dove VERSION è il numero di versione MAJOR Node.js. Ad esempio, Node.js 20 utilizza 20.

Per le altre versioni di Node.js supportate e la versione di Ubuntu corrispondente per la tua versione di Node.js, consulta la pianificazione del supporto dell'esecuzione.

Versione Node.js

Il runtime Node.js utilizza l'ultima release stabile della versione specificata nel file app.yaml. App Engine si aggiorna automaticamente alle nuove versioni patch e release secondarie, ma non aggiorna automaticamente la versione principale.

Ad esempio, il deployment della tua applicazione potrebbe essere eseguito in Node.js 10.9.4 e in versioni successive, aggiornato automaticamente alla versione 10.10.0, ma non verrà aggiornato automaticamente a Node.js 12.x.x.

Poiché le versioni secondarie e patch vengono aggiornate automaticamente, se presenti, la proprietà engines.node nel file package.json può specificare solo la versione principale ed essere compatibile con la versione Node.js specificata nel file app.yaml.

Ad esempio per 20:

• 20.x.x
• ^20.0.0
• ~20
• >=6

Se specifichi una versione Node.js incompatibile nel file package.json, il deployment non andrà a buon fine e verrà visualizzato un messaggio di errore.

Dipendenze

Durante il deployment, il runtime installa le dipendenze utilizzando il comando npm install. Il runtime supporta anche i gestori di pacchetti Yarn (yarn.lock) e Pnpm (pnpm-lock.yaml). Per ulteriori informazioni, consulta Specifica delle dipendenze. Poiché il runtime esegue una nuova installazione, non è necessario caricare la cartella node_modules.

Nota: per impostazione predefinita, gcloud CLI non carica la cartella node_modules. Puoi cambiare i file che vengono ignorati utilizzando il file .gcloudignore.

Per supportare i pacchetti Node.js che richiedono estensioni native, il runtime include pacchetti di sistema che ti consentono di utilizzare strumenti come ImageMagick, FFmpeg e Chrome headless. Consulta l'elenco completo dei pacchetti nella sezione Pacchetti di sistema inclusi. Per richiedere un pacchetto, segnala il problema in Issue Tracker.

Script di build NPM

Per impostazione predefinita, il runtime Node.js esegue npm run build se viene rilevato uno script build in package.json. 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 file package.json: "gcp-build":"". Per maggiori dettagli sulla configurazione di package.json, consulta Configurazioni di buildpack Node.js.

• 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 sulla specifica delle variabili di ambiente di build, consulta la sezione build_env_variables nel file app.yaml.

Avvio dell'applicazione

Per impostazione predefinita, il runtime avvia l'applicazione eseguendo node server.js. Se specifichi uno script start nel file package.json, il runtime esegue invece lo script di avvio specificato. Ad esempio:

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

Affinché la tua app riceva richieste HTTP, lo script start deve avviare un server web in ascolto sull'host 0.0.0.0 e sulla porta specificata dalla PORT variabile di ambiente, accessibile in Node.js come process.env.PORT.

Per ottenere prestazioni ottimali, lo script start deve essere leggero ed escludere i passaggi di build, poiché viene eseguito ogni volta che viene creata una nuova istanza della tua applicazione.

Puoi ignorare questo comportamento specificando uno script nel campo entrypoint in app.yaml. Anziché eseguire node server.js o uno script di avvio, il runtime avvia l'applicazione con il comando specificato in entrypoint.

Variabili di ambiente

Le seguenti variabili di ambiente sono impostate dal runtime:

Variabile di ambiente	Descrizione
GAE_APPLICATION	L'ID della tua applicazione App Engine. Questo ID è preceduto dal prefisso "region code~", ad esempio "e~" per le applicazioni distribuite in Europa.
GAE_DEPLOYMENT_ID	L'ID del deployment corrente.
GAE_ENV	L'ambiente App Engine. Impostato su standard.
GAE_INSTANCE	L'ID dell'istanza su cui il servizio è attualmente in esecuzione.
GAE_MEMORY_MB	La quantità di memoria disponibile per il processo di richiesta, in MB.
GAE_RUNTIME	Il runtime specificato nel file app.yaml.
GAE_SERVICE	Il nome del servizio specificato nel file app.yaml. Se non viene specificato alcun nome del servizio, è impostato su default.
GAE_VERSION	L'etichetta della versione corrente del servizio.
GOOGLE_CLOUD_PROJECT	L'ID progetto Google Cloud associato alla tua applicazione.
PORT	La porta che riceve le richieste HTTP.
NODE_ENV (disponibile solo nel runtime Node.js)	Imposta su production quando viene eseguito il deployment del servizio.

Puoi definire variabili di ambiente aggiuntive nel file app.yaml, ma i valori precedenti non possono essere sostituiti, ad eccezione di NODE_ENV.

HTTPS e proxy di forwarding

App Engine termina le connessioni HTTPS al bilanciatore del carico e inoltra le richieste 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);

Filesystem

Il runtime include un file system completo. Il file system è di sola lettura tranne per la posizione /tmp, che è un disco virtuale che archivia i dati nella RAM dell'istanza di App Engine.

Server dei metadati

Ogni istanza della tua applicazione può utilizzare il server di metadati App Engine per eseguire query sulle informazioni sull'istanza e sul progetto.

Nota: i metadati personalizzati non sono supportati nell'ambiente standard.

Puoi accedere al server dei metadati tramite i seguenti endpoint:

• http://metadata
• http://metadata.google.internal

Le richieste inviate al server di metadati devono includere l'intestazione della richiesta Metadata-Flavor: Google. Questa intestazione indica che la richiesta è stata inviata con l'intento di recuperare i valori dei metadati.

La seguente tabella elenca gli endpoint in cui è possibile effettuare richieste HTTP per metadati specifici:

Endpoint dei metadati	Descrizione
/computeMetadata/v1/project/numeric-project-id	Il numero di progetto assegnato al progetto.
/computeMetadata/v1/project/project-id	L'ID progetto assegnato al progetto.
/computeMetadata/v1/instance/region	La regione in cui è eseguita l'istanza.
/computeMetadata/v1/instance/service-accounts/default/aliases
/computeMetadata/v1/instance/service-accounts/default/email	L'indirizzo email dell'account di servizio predefinito assegnato al progetto.
/computeMetadata/v1/instance/service-accounts/default/	Elenca tutti gli account di servizio predefiniti per il tuo progetto.
/computeMetadata/v1/instance/service-accounts/default/scopes	Elenca tutti gli ambiti supportati per gli account di servizio predefiniti.
/computeMetadata/v1/instance/service-accounts/default/token	Restituisce il token di autenticazione che può essere utilizzato per autenticare l'applicazione ad altre API Google Cloud.

Ad esempio, per recuperare l'ID progetto, invia una richiesta a http://metadata.google.internal/computeMetadata/v1/project/project-id.