Creazione di un'applicazione Node.js

Specifica delle versioni di Node.js

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

Uso: package.json

Puoi specificare la versione Node.js della tua applicazione durante il deployment configurando il campo engines.node in package.json. Per configurare il buildpack in modo che utilizzi la versione più recente di Node.js v16 durante il deployment della tua app, puoi utilizzare i seguenti valori in package.json:

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

Uso: GOOGLE_NODEJS_VERSION

È anche possibile specificare la versione Node.js tramite 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 viene fornito alcun valore, viene utilizzata la versione LTS più recente di Node.js

Per configurare il buildpack in modo da utilizzare Node.js 16 durante il deployment dell'app:

pack build --builder=gcr.io/buildpacks/builder \
   sample-functions-framework-node \
   --env GOOGLE_NODEJS_VERSION=16.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 sulla creazione dell'applicazione con variabili di ambiente.

Suggerimenti

  • Il campo engines.node può utilizzare un vincolo del server. La libreria specifica che utilizziamo per i buildpack Node.js è Masterminds/semver.
  • Evita di utilizzare valori di maggiore di (>) in engines.node
  • Durante il deployment dell'applicazione nell'ambiente standard di App Engine, la proprietà engines.node deve essere compatibile con il runtime specificato in app.yaml
  • Puoi trovare ulteriore documentazione sull'opzione di configurazione di engines.node in package.json nella documentazione ufficiale relativa alla Gestione dei partner di rete nell'argomento Motori
  • Quando esegui il deployment di una funzione in Cloud Functions, la proprietà engines.node deve essere compatibile con il runtime utilizzato per il deployment della funzione

Installazione delle dipendenze

Utilizzo di Gestione dei partner di rete

  • NPM è il gestore di pacchetti predefinito.
  • Se possibile, utilizza package-lock.json per migliorare le prestazioni della cache.
  • Per impostazione predefinita, sono installate solo le dipendenze di produzione.
  • Puoi specificare la sezione della versione npm utilizzando il campo engines.npm nel file package.json.

Utilizzo di Yarn

  • Viene utilizzato Yarn quando includi il file yarn.lock nel tuo progetto.
  • Puoi specificare la versione filato da utilizzare nel campo engines.yarn del file package.json.
  • La modalità PnP Yarn2 è supportata se il tuo progetto include un .yarn/cache.

Utilizzo di Pnpm

  • Quando includi il file pnpm-lock.yaml nel progetto, viene invece utilizzato Pnpm.
  • Puoi specificare una versione di pnpm nel campo engines.pnpm del file package.json.
  • Per un esempio funzionante, vedi l'app sample-node-pnpm.

Utilizzo di moduli privati

Puoi utilizzare un modulo npm privato specificando 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 da 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 di Artifact Registry per l'account di servizio Cloud Build. Devi solo elencare il repository Artifact Registry nel file .npmrc quando utilizzi NPM o Yarn versione 1. Ad esempio, quando utilizzi Gestione dei partner di rete 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 successiva, devi solo elencare il repository Artifact Registry nel tuo 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 da altri repository

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

Non includere il file .npmrc se non stai utilizzando repository privati, in quanto potrebbe aumentare il tempo di deployment delle tue funzioni.

Formato file

Se utilizzi un file .npmrc per impostare un token di autorizzazione personalizzato, questo deve includere la riga riportata di seguito.

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

Sostituisci:

  • REGISTRY_DOMAIN: il nome di dominio del registry 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 registro npm. Può essere il valore di testo letterale del token o la 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 comando gcloud functions deploy. Per ulteriori dettagli sul token di autenticazione NPM, consulta il tutorial su NPM sui moduli privati.

Esecuzione di passaggi di build personalizzati durante il deployment

Per impostazione predefinita, l'esecuzione di npm run build viene eseguita se è specificato uno script nel file package.json. Tuttavia, puoi specificare passaggi di build personalizzati per eseguire l'override del comportamento predefinito ed eseguire solo gli script desiderati 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 in package.json.

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

Uso: 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 dettagli completi, consulta Variabili di ambiente.

Uso: 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"
  ...
}

Punto di ingresso dell'applicazione

Il buildpack Node.js eseguirà il comando specificato nel campo scripts.start di package.json. Se il criterio scripts.start non è impostato, il buildpack verrà eseguito npm start.

Ti consigliamo di utilizzare un Procfile perché elimina npm o yarn dal percorso.

Variabili di ambiente

Puoi impostare variabili di ambiente per configurare le build della tua immagine container.

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

NPM_CONFIG_<key>

Consulta la documentazione.

Esempio: NPM_CONFIG_FLAG=value passa -flag=value a npm i comandi.

NODE_ENV

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

Esempio: NODE_ENV=development installa sia dependencies sia devDependencies specificati in package.json.

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 viene eseguito nell'ordine in cui è riportato ogni script.

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

Esempi:

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