Creazione di un'applicazione Node.js

Specificare le versioni di Node.js

Il progetto Buildpacks fornisce il supporto per le release Current e Active LTS di Node.js. Sono disponibili release precedenti di Node.js, ma potrebbero non essere gestite attivamente dal progetto.

Utilizzare package.json

Puoi specificare la versione di Node.js della tua applicazione durante il deployment configurando il campo engines.node nel file package.json. Per configurare il buildpack in modo che utilizzi l'ultima versione di Node.js durante il deployment dell'app, aggiungi i seguenti valori in package.json:

"engines": {
  "node": "24.x.x"
}

Utilizzare GOOGLE_NODEJS_VERSION

Puoi anche specificare la versione di Node.js utilizzando la variabile di ambiente GOOGLE_NODEJS_VERSION. Se vengono impostate entrambe le configurazioni, il valore GOOGLE_NODEJS_VERSION ha la precedenza sulla proprietà engines.node. Se non fornisci una versione, il buildpack utilizza la versione LTS più recente di Node.js.

Per configurare il buildpack in modo che utilizzi Node.js 24 durante il deployment dell'app, esegui il seguente comando:

pack build --builder=gcr.io/buildpacks/builder \
   sample-functions-framework-node \
   --env GOOGLE_NODEJS_VERSION=24.x.x

Puoi anche utilizzare un descrittore di progetto project.toml per codificare la variabile di ambiente insieme ai file di progetto. Consulta le istruzioni per la creazione dell'applicazione con le variabili di ambiente.

Suggerimenti

• Il campo engines.node può accettare un vincolo semver. La libreria specifica che utilizziamo per i buildpack Node.js è Masterminds/semver
• Evita di utilizzare specificatori maggiori di (>) nel campo engines.node.
• Quando esegui il deployment dell'applicazione nell'ambiente standard di App Engine, la proprietà engines.node deve essere compatibile con il runtime specificato in app.yaml. Per saperne di più sull'opzione di configurazione engines.node nel file package.json, consulta la documentazione ufficiale di NPM per l'argomento dei motori.
• Quando esegui il deployment di una funzione in Cloud Run Functions, la proprietà engines.node deve essere compatibile con il runtime utilizzato per il deployment della funzione

Installare le dipendenze

NPM è il gestore di pacchetti predefinito per tutte le versioni di Node.js. La sezione seguente include le dipendenze compatibili per le applicazioni Node.js.

Gestore di pacchetti NPM

• NPM è il gestore di pacchetti predefinito.
• Quando possibile, utilizza package-lock.json per migliorare il rendimento della cache.
• Per impostazione predefinita, vengono installate solo le dipendenze di produzione.
• Specifica la versione di npm utilizzando il campo engines.npm nel file package.json. Per saperne di più, consulta la documentazione di NPM.

Gestore di pacchetti Yarn

• Il buildpack utilizza Yarn quando includi il file yarn.lock nel progetto.
• Specifica la versione di Yarn nel campo engines.yarn del file package.json.
• Il buildpack supporta la modalità Yarn2 PnP se il progetto include una cartella .yarn/cache.

Gestore di pacchetti Pnpm

• Il buildpack utilizza Pnpm quando includi il file pnpm-lock.yaml nel progetto.
• Specifica la versione di pnpm nel campo engines.pnpm del file package.json.
• Per un esempio pratico, consulta sample-node-pnpm.

Gestore di pacchetti Bun

Anteprima — supporto per il gestore di pacchetti Bun

Questa funzionalità è soggetta ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Il buildpack Node.js supporta il gestore di pacchetti Bun, google.nodejs.bun buildpack per l'installazione delle dipendenze. Per utilizzare il gestore di pacchetti Bun:

• Crea un file bun.lock o bun.lockb nella directory principale per il rilevamento automatico.
• In alternativa, puoi anche impostare esplicitamente la variabile di ambiente GOOGLE_PACKAGE_MANAGER su bun. Con questo metodo, non devi creare e gestire i file di blocco.
• Il progetto deve includere un file package.json. Puoi specificare una versione di Bun nel campo engines.bun o packageManager del file package.json. Se non viene specificata alcuna versione, il buildpack utilizza per impostazione predefinita l'ultima release stabile.

Per saperne di più sul deployment in Cloud Run, consulta Specificare le dipendenze in Node.js.

Per saperne di più sul gestore di pacchetti Bun, consulta la Bun documentazione.

Precedenza del gestore di pacchetti

Il buildpack Node.js determina il gestore di pacchetti in base alla configurazione nel seguente ordine di precedenza:

1. Il GOOGLE_PACKAGE_MANAGER ha sempre la precedenza. Questa variabile di ambiente supporta solo bun (anteprima).

2. Il buildpack verifica la presenza di file di blocco nel seguente ordine:

   • Yarn - yarn.lock
   • pnpm - pnpm-lock.yaml
   • Bun - bun.lock o bun.lockb
   • NPM - package-lock.json

3. Se non imposti la variabile di ambiente o utilizzi un file di blocco, il buildpack utilizza per impostazione predefinita NPM.

Moduli privati

Utilizza un modulo npm privato fornendo le impostazioni per l'autenticazione con il registro in un file .npmrc nella directory della funzione. Se utilizzi Yarn versione 2 o successive come gestore di pacchetti, questo file è denominato .yarnrc.yml.

Moduli privati di Artifact Registry

Un repository di pacchetti Node.js di Artifact Registry può ospitare moduli privati per la tua funzione. Quando esegui il deployment di una funzione Buildpacks, il processo di compilazione genera automaticamente le credenziali Artifact Registry per il service account Cloud Build. Devi solo elencare il repository Artifact Registry nel file .npmrc quando utilizzi NPM o Yarn versione 1. Ad esempio, quando utilizzi NPM o Yarn versione 1:

@SCOPE:registry=https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
//REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME:always-auth=true

Se utilizzi Yarn versione 2 o successive, devi solo elencare il repository Artifact Registry nel file .yarnrc.yml senza credenziali aggiuntive. Ad esempio:

npmScopes:
  SCOPE:
    npmRegistryServer: https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
    npmAlwaysAuth: true

Moduli privati di altri repository

La documentazione di npm spiega come creare token di accesso di sola lettura personalizzati. Sconsigliamo l'utilizzo del file .npmrc creato nella directory home perché contiene un token di lettura/scrittura. Le autorizzazioni in scrittura non sono richieste durante il deployment e potrebbero rappresentare un rischio per la sicurezza.

Non includere il file .npmrc se non utilizzi repository privati, in quanto può aumentare il tempo di deployment delle tue funzioni.

Nota: se utilizzi autorizzazioni personalizzate (ad esempio quelle necessarie per VPC), assicurati di consentire esplicitamente alle tue funzioni di accedere al repository privato di destinazione.

Formato file

Se utilizzi un file .npmrc per impostare un token di autenticazione personalizzato, includi quanto segue:

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

Sostituisci:

• REGISTRY_DOMAIN: il nome di dominio del tuo registro npm privato. Ad esempio, se l'host del repository è npmjs.org, imposta questo campo su registry.npmjs.org.

• AUTH_TOKEN: il token di autorizzazione per il tuo registro npm. Può trattarsi del valore di testo letterale del token o della stringa di testo ${NPM_TOKEN}, che il comando npm sostituisce con il valore effettivo del token dell'ambiente.

  Puoi impostare la variabile di ambiente $NPM_TOKEN con l' --set-build-env-vars argomento sul comando gcloud functions deploy. Per maggiori dettagli sul token di autenticazione NPM, consulta il tutorial NPM sui moduli privati.

Eseguire passaggi di build personalizzati durante il deployment

Per impostazione predefinita, viene eseguito npm run build se viene specificato uno script nel file package.json. Tuttavia, puoi specificare passaggi di build personalizzati per sostituire il comportamento predefinito ed eseguire solo gli script che vuoi durante la build. Puoi controllare i passaggi di build utilizzando la variabile di ambiente GOOGLE_NODE_RUN_SCRIPTS o gcp-build nel file package.json.

Puoi utilizzare un solo metodo. Tieni presente che la variabile di ambiente GOOGLE_NODE_RUN_SCRIPTS ha la precedenza e sostituisce qualsiasi elemento specificato per gcp-build in package.json.

Per impostazione predefinita, quando configuri i passaggi di build personalizzati, vengono installate prima le dependencies e le devDependencies nel file package.json prima dell'esecuzione di script o comandi. Per sostituire il comportamento predefinito, puoi utilizzare la NODE_ENV variabile di ambiente.

Utilizzare GOOGLE_NODE_RUN_SCRIPTS

Puoi passare la variabile di ambiente GOOGLE_NODE_RUN_SCRIPTS alla build per controllare gli script da eseguire. Puoi specificare uno o più script oppure passare una variabile di ambiente vuota per impedire l'esecuzione del comportamento predefinito, ad esempio GOOGLE_NODE_RUN_SCRIPTS=. Per informazioni complete, consulta Variabili di ambiente.

Utilizzare package.json

L'aggiunta di gcp-build nel file package.json esegue solo npm run gcp-build, il che significa che sostituisce il comportamento predefinito. Puoi specificare uno o più comandi oppure specificare una stringa vuota per impedire l'esecuzione di qualsiasi comando, ad esempio "gcp-build":"".

"scripts": {
  ...
  "gcp-build": "npm run lint && npm run build"
  ...
}

Entry point dell'applicazione

Il buildpack Node.js esegue il comando specificato nel campo scripts.start del file package.json. Se non configuri il campo scripts.start, il buildpack esegue il comando npm start.

Ti consigliamo di utilizzare un Procfile perché rimuove il gestore di pacchetti dal percorso e consente l'esecuzione diretta.

Variabili di ambiente

Puoi impostare le variabili di ambiente per configurare le build dell'immagine container.

Il buildpack Node.js supporta le seguenti variabili di ambiente per personalizzare il container.

NODE_ENV

Specifica l'ambiente di sviluppo durante la build; impostato per npm install.

Esempio: NODE_ENV=development installa sia le dependencies che le devDependencies specificate in package.json.

NPM_CONFIG_<key>

Specifica il parametro di configurazione, ad esempio NPM_CONFIG_FLAG=value passa -flag=value ai comandi npm.

Per informazioni su questa variabile di ambiente, consulta Config nella documentazione di NPM.

GOOGLE_PACKAGE_MANAGER (anteprima)

Supporta solo il gestore di pacchetti Bun. Questa variabile di ambiente funge da override per il processo di rilevamento automatico. Ad esempio, GOOGLE_PACKAGE_MANAGER=bun forza l'utilizzo di Bun anche se non crei un file di blocco.

GOOGLE_NODE_RUN_SCRIPTS

Specifica un elenco ordinato di script npm da package.json da eseguire dopo l'installazione delle dipendenze. L'elenco deve essere separato da virgole ed eseguito nell'ordine in cui elenchi ogni script.

Quando specifichi GOOGLE_NODE_RUN_SCRIPTS, vengono eseguiti solo gli script che elenchi. Ad esempio, se vuoi impedire l'esecuzione di npm run build predefinito, specifica la variabile di ambiente senza un valore.

Esempi:

• GOOGLE_NODE_RUN_SCRIPTS=lint,build esegue npm run lint e poi npm run build.
• GOOGLE_NODE_RUN_SCRIPTS= non esegue script.