Il runtime Node.js è lo stack software responsabile dell'installazione del codice del servizio web e delle relative 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 di Node.js MAJOR. Ad esempio, per utilizzare l'ultima versione di Node.js, Node.js 24 (anteprima), specifica
24.
Per altre versioni di Node.js supportate e la versione di Ubuntu corrispondente alla tua versione di Node.js, consulta la pianificazione del supporto del runtime.
Versione di Node.js
L'ultima versione supportata di Node.js è la 24 (anteprima). Il runtime Node.js utilizza l'ultima release stabile della versione
specificata nel file app.yaml. App Engine si aggiorna automaticamente
alle nuove versioni di patch e release secondarie, ma non aggiornerà automaticamente
la versione principale.
Ad esempio, la tua applicazione potrebbe essere implementata in Node.js 10.9.4 e versioni successive aggiornate 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 24 (anteprima):
24.x.x^24.0.0~24>=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 comando
npm install. Il runtime supporta anche i gestori di pacchetti Yarn (yarn.lock) e Pnpm (pnpm-lock.yaml).
Per ulteriori informazioni, vedi
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 in 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 controllo aggiuntivo 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 nella build, devi:
- Aggiungi uno script
gcp-buildcon un valore vuoto nel filepackage.json:"gcp-build":"". Per informazioni dettagliate sulla configurazione dipackage.json, vedi Configurazioni dei buildpack Node.js. Aggiungi la variabile di ambiente di build
GOOGLE_NODE_RUN_SCRIPTScon 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 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, 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 vengono impostate dal runtime:
| Variabile di ambiente | Descrizione |
|---|---|
GAE_APPLICATION
|
L'ID della tua applicazione App Engine. Questo ID ha il prefisso "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. Imposta 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 attuale 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 il servizio viene implementato. |
Puoi
definire variabili di ambiente aggiuntive nel file app.yaml,
ma i valori sopra indicati non possono essere sostituiti, ad eccezione di NODE_ENV.
Proxy HTTPS e 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 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'impostazione trust proxy:
app.set('trust proxy', true);
Tieni presente che l'impostazione di trust proxy su true può rendere la
proprietà req.ip vulnerabile allo spoofing dell'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 di metadati
Ogni istanza della tua applicazione può utilizzare il server metadati di App Engine per eseguire query sulle informazioni relative all'istanza e al tuo progetto.
Puoi accedere al server dei metadati tramite i seguenti endpoint:
http://metadatahttp://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 effettuare richieste HTTP per metadati specifici:
| Endpoint dei metadati | Descrizione |
|---|---|
/computeMetadata/v1/project/numeric-project-id |
Il numero di progetto assegnato al tuo progetto. |
/computeMetadata/v1/project/project-id |
L'ID progetto assegnato al tuo 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'email del account di servizio predefinito assegnato al tuo progetto. |
/computeMetadata/v1/instance/service-accounts/default/ |
Elenca tutti i service account predefiniti per il tuo 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 con altre API Google Cloud. |
Ad esempio, per recuperare l'ID progetto, invia una richiesta a
http://metadata.google.internal/computeMetadata/v1/project/project-id.