Il runtime Node.js è lo stack software responsabile dell'installazione del codice e delle sue dipendenze del servizio web 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, per utilizzare l'ultima versione di Node.js, Node.js 22 (anteprima), specifica 22
.
Per le altre versioni di Node.js supportate e la versione di Ubuntu corrispondente alla 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 dell'applicazione potrebbe essere eseguito a Node.js 10.9.4 e in seguito 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 22 (anteprima):
22.x.x
^22.0.0
~22
>=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
Specificare le 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 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 di Gestione dei partner di rete
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 maggiore 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":""
. Per maggiori dettagli sulla configurazione dipackage.json
, consulta Configurazioni buildpack Node.js. 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
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
dovrebbe 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 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 di cui è stato eseguito il deployment in Europa. |
GAE_DEPLOYMENT_ID |
L'ID del deployment attuale. |
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 del 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 Node.js) |
Imposta su production quando viene eseguito il deployment del servizio. |
Puoi definire altre variabili di ambiente nel file app.yaml
, ma i valori precedenti non possono essere sostituiti, ad eccezione di NODE_ENV
.
HTTPS e proxy 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 da considerare attendibile il proxy.
Con Express.js, utilizza l'impostazione trust proxy
:
app.set('trust proxy', true);
File system
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 di App Engine.
Server metadati
Ogni istanza dell'applicazione può utilizzare il server metadati di App Engine per eseguire query sulle informazioni sull'istanza e sul progetto.
Puoi accedere al server 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'intento di recuperare i valori dei metadati.
Nella tabella seguente sono elencati 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 è 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 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 su altre API Google Cloud. |
Ad esempio, per recuperare il tuo ID progetto, invia una richiesta a http://metadata.google.internal/computeMetadata/v1/project/project-id
.