Ambiente di runtime Node.js

Il runtime Node.js è lo stack software che installa il codice del servizio web e le relative dipendenze ed esegue il servizio.

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

runtime: nodejsVERSION

Dove VERSION è il numero di versione MAJOR di Node.js. Ad esempio, per utilizzare l'ultima versione di Node.js, Node.js 26 (anteprima), specifica 26.

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

Versione di Node.js

L'ultima versione di Node.js supportata è la 26 (anteprima). Il runtime Node.js utilizza l'ultima release stabile della versione specificata nel file app.yaml. App Engine esegue automaticamente l'aggiornamento alle nuove versioni di patch e release secondarie, ma non esegue automaticamente l'aggiornamento della versione principale.

Ad esempio, la tua applicazione potrebbe essere sottoposta a deployment in Node.js 10.9.4 e versioni successive e aggiornata automaticamente alla versione 10.10.0, ma non verrà aggiornata automaticamente a Node.js 12.x.x.

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

Ad esempio, per la versione 26 (anteprima):

  • 26.x.x
  • ^26.0.0
  • ~26
  • >=6

Se specifichi una versione di 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 npm install comando. Il runtime supporta anche i gestori di pacchetti Yarn (yarn.lock) e Pnpm (pnpm-lock.yaml). Per saperne di più, consulta Specifica delle dipendenze. Poiché il runtime esegue una nuova installazione, non è necessario caricare la cartella node_modules.

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

Script di build NPM

Per impostazione predefinita, quando esegui il deployment dell'app in App Engine, il runtime 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 build prima di avviare l' applicazione, puoi fornire un passaggio di build personalizzato aggiungendo uno script gcp-build al file package.json.

Per impedire l'esecuzione dello script npm run build durante la build, devi:

  • Aggiungere uno script gcp-build con un valore vuoto nel file package.json: "gcp-build":"". Per informazioni dettagliate sulla configurazione di package.json, consulta Configurazioni dei buildpack Node.js.

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

    build_env_variables:
  GOOGLE_NODE_RUN_SCRIPTS: ''
Per informazioni dettagliate 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 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 un rendimento ottimale, lo script start deve essere leggero ed escludere i passaggi di build, perché viene eseguito ogni volta che viene creata una nuova istanza dell'applicazione.

Puoi ignorare questo comportamento specificando uno script nel entrypoint campo 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 dell'applicazione App Engine. Questo ID è preceduto da "region code~" ad esempio "e~" per le applicazioni sottoposte a deployment 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 è attualmente in esecuzione il servizio.
GAE_MEMORY_MB La quantità di memoria disponibile per il processo dell'applicazione, 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, viene impostato su default.
GAE_VERSION L'etichetta della versione corrente del servizio.
GOOGLE_CLOUD_PROJECT L' Google Cloud ID progetto associato all'applicazione.
PORT La porta che riceve le richieste HTTP.
NODE_ENV (disponibile solo nel runtime Node.js) Impostato su production quando il servizio viene sottoposto a deployment.

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

Proxy HTTPS e di forwarding

App Engine termina le connessioni HTTPS nel bilanciatore del carico e inoltra le richieste all'applicazione. Alcune applicazioni devono determinare l'IP e il protocollo della richiesta originale. L'indirizzo IP dell'utente è disponibile nell'intestazione standard X-Forwarded-For. Le applicazioni che richiedono queste informazioni devono configurare il framework web in modo che consideri attendibile il proxy.

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

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

Tieni presente che l'impostazione di trust proxy su true può esporre la req.ip proprietà alla vulnerabilità di spoofing IP.

Filesystem

Il runtime include un filesystem completo. Il filesystem è di sola lettura, ad eccezione della località /tmp, che è un disco virtuale che archivia i dati nella RAM dell'istanza App Engine.

Server di metadati

Ogni istanza dell'applicazione può utilizzare il server di metadati di App Engine per eseguire query sulle informazioni relative all'istanza e al progetto.

Puoi accedere al server di 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'intenzione di recuperare i valori dei metadati.

La tabella seguente elenca gli endpoint in cui puoi 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 è in esecuzione l'istanza.
/computeMetadata/v1/instance/service-accounts/default/aliases
/computeMetadata/v1/instance/service-accounts/default/email L'indirizzo email del account di servizio predefinito assegnato al progetto.
/computeMetadata/v1/instance/service-accounts/default/ Elenca tutti i service account predefiniti per il progetto.
/computeMetadata/v1/instance/service-accounts/default/scopes Elenca tutti gli ambiti supportati per i service account predefiniti.
/computeMetadata/v1/instance/service-accounts/default/token Restituisce il token di autenticazione che può essere utilizzato per autenticare l'applicazione in altre API Google Cloud.

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