Creazione di un'applicazione Node.js

Specificare le versioni di Node.js

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

Utilizza 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 la versione più recente di Node.js durante il deployment dell'app, aggiungi i seguenti valori in package.json:

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

Utilizza 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 questo 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 creare l'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 maggiore 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 engines.
• Quando esegui il deployment di una funzione su Cloud Run Functions, la proprietà engines.node deve essere compatibile con il runtime utilizzato per il deployment della funzione

Installa le dipendenze

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

Gestore di pacchetti NPM

• NPM è il gestore di pacchetti predefinito.
• Ove 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

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

Gestore di pacchetti Pnpm

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

Gestore di pacchetti Bun

Anteprima — Support for the Bun package manager

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione 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 delle fasi 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 è necessario 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 Specifica delle dipendenze in Node.js.

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

Priorità del gestore di pacchetti

Il buildpack Node.js determina il gestore dei 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 controlla i file di blocco nel seguente ordine:

   • Gomitolo - yarn.lock
   • pnpm - pnpm-lock.yaml
   • Panino: bun.lock o bun.lockb
   • NPM - package-lock.json

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

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. Quando utilizzi NPM o Yarn versione 1, devi solo elencare il repository Artifact Registry nel file .npmrc. 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'argomento --set-build-env-vars sul tuo comando gcloud functions deploy. Per maggiori dettagli sul token di autenticazione NPM, consulta il tutorial NPM sui moduli privati.

Esecuzione di passaggi di build personalizzati durante il deployment

Per impostazione predefinita, npm run build viene eseguito se uno script è specificato nel file package.json. Tuttavia, puoi specificare passaggi di build personalizzati per ignorare 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 valore specificato per gcp-build nel file package.json.

Per impostazione predefinita, quando configuri passaggi di build personalizzati, vengono installati prima dependencies e devDependencies nel file package.json prima dell'esecuzione di script o comandi. Per eseguire l'override del comportamento predefinito, puoi utilizzare la variabile di ambiente NODE_ENV.

Utilizza GOOGLE_NODE_RUN_SCRIPTS

Puoi passare la variabile di ambiente GOOGLE_NODE_RUN_SCRIPTS alla build per controllare quali script vengono eseguiti. 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 tutti i dettagli, vedi Variabili di ambiente.

Utilizza 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 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 su npm install.

Esempio: NODE_ENV=development installa sia dependencies che devDependencies specificati 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 impone 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 e deve essere 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.