Questa pagina è stata tradotta dall'API Cloud Translation.

Ambiente di runtime Node.js

Il runtime Node.js è lo stack software responsabile dell'installazione del codice del servizio web e delle relative dipendenze ed esegue il servizio.

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

runtime: nodejsVERSION

dove VERSION è il numero di versione di Node.js MAJOR. Ad esempio, per utilizzare la versione più recente di Node.js, Node.js 22, specifica 22.

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 Node.js

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

Ad esempio, l'applicazione potrebbe essere dipiattata su 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 le 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 di Node.js specificata nel file app.yaml.

Ad esempio per 22:

22.x.x
^22.0.0
~22
>=6

Se nel file package.json specifichi una versione di Node.js incompatibile, 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 dei pacchetti Yarn (yarn.lock) e Pnpm (pnpm-lock.yaml). Per ulteriori informazioni, consulta Specificare le dipendenze. Poiché il runtime esegue una nuova installazione, non è necessario caricare la node_modules cartella.

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 in Pacchetti di sistema inclusi. Per richiedere un pacchetto, segnala un problema nell'Issue Tracker.

Script di build NPM

Per impostazione predefinita, il runtime di 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 compilazione prima di avviare l'applicazione, puoi fornire un passaggio di compilazione 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 informazioni dettagliate sulla configurazione di package.json, consulta Configurazioni dei buildpack Node.js.
Aggiungi la variabile di ambiente di compilazione GOOGLE_NODE_RUN_SCRIPTS con un valore vuoto nel file app.yaml.
```
build_env_variables:
  GOOGLE_NODE_RUN_SCRIPTS: ''
```

Per informazioni dettagliate su come specificare le variabili di ambiente di compilazione, consulta la sezione build_env_variables del 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 avvia 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 il massimo rendimento, lo script start deve essere leggero ed escludere i passaggi di compilazione, in quanto viene eseguito ogni volta che viene creata una nuova istanza dell'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 vengono impostate dal runtime:

Variabile di ambiente	Descrizione
`GAE_APPLICATION`	L'ID della tua applicazione App Engine. Questo ID è preceduto da "`region code`~", ad esempio "e~" per le applicazioni di cui è stato eseguito il 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 di 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 di servizio, viene 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 di Node.js)	Imposta su `production` quando il servizio viene disegnato.

Puoi definire variabili di ambiente aggiuntive nel file app.yaml, ma i valori sopra indicati non possono essere sostituiti, tranne per NODE_ENV.

Proxy HTTPS e di inoltro

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 originale. 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 attenda il proxy.

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

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

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

Filesystem

Il runtime include un file system completo. Il file system è di sola lettura, ad eccezione della posizione /tmp, che è un disco virtuale che memorizza i dati nella RAM dell'istanza App Engine.

Server dei metadati

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

Puoi accedere al server dei metadati tramite i seguenti endpoint:

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

Le richieste inviate al server dei 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 inviare 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 dell'account di servizio predefinito assegnato al progetto.
`/computeMetadata/v1/instance/service-accounts/default/`	Elenca tutti gli account di servizio 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 la tua 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.