Abhängigkeiten in Node.js angeben

Eine Funktion kann externe Node.js-Module sowie lokale Daten verwenden. Abhängigkeiten in Node.js werden mit npm verwaltet und in einer Metadatendatei namens package.json ausgedrückt. Sie können npm, yarn, pnpm, oder Bun verwenden, um Node.js-Abhängigkeiten zu installieren.

Das Node.js Functions Framework ist eine erforderliche Abhängigkeit für alle Funktionen. Obwohl Cloud Run-Funktionen es bei der Erstellung der Funktion für Sie installiert, empfehlen wir, es zur Klarstellung hinzuzufügen.

Wenn Ihre Funktion private Abhängigkeiten benötigt, sollten Sie functions-framework in Ihre private Registry spiegeln. Fügen Sie das gespiegelte functions-framework als Abhängigkeit zu Ihrer Funktion hinzu, um die Installation des Pakets aus dem öffentlichen Internet zu vermeiden.

Zum Angeben einer Abhängigkeit für die Funktion fügen Sie diese der Datei package.json hinzu.

Wenn das Node.js-Buildpack eine Sperrdatei wie package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lock, oder bun.lockb in Ihrem Projekt erkennt, hat diese Sperrdatei Priorität, wenn Sie Abhängigkeiten mit npm ci, yarn install, pnpm install, oder bun installinstallieren.

Im folgenden Beispiel ist eine Abhängigkeit in der Datei package.json aufgeführt:

{
  "dependencies": {
    "escape-html": "^1.0.3"
  }
}

Cloud Run importiert die Abhängigkeit in die Funktion:

const functions = require('@google-cloud/functions-framework');
const escapeHtml = require('escape-html');

/**
 * Responds to an HTTP request using data from the request body parsed according
 * to the "content-type" header.
 *
 * @param {Object} req Cloud Function request context.
 * @param {Object} res Cloud Function response context.
 */
functions.http('helloHttp', (req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || 'World')}!`);
});

Node.js-Module lokal mit npm installieren

Die einfachste Methode zum lokalen Installieren eines Node.js-Moduls besteht darin, den Befehl npm install in dem Ordner zu verwenden, der die Cloud Run-Funktion enthält. Mit dem folgenden Befehl wird beispielsweise das Modul uuid hinzugefügt:

npm install uuid

Im Befehl sind zwei Schritte kombiniert:

1. Die neueste Version des Moduls wird als Abhängigkeit in der Datei package.json gekennzeichnet. Dies ist sehr wichtig, denn Cloud Run-Funktionen installiert nur Module, die in der Datei package.json deklariert sind.
2. Das Modul wird in das Verzeichnis node_modules heruntergeladen. So können Sie das Modul beim lokalen Entwickeln verwenden.

Falls npm nicht auf Ihrem Computer installiert ist, besorgen Sie sich npm.

Hinweis: npm-Pakete sind für eine Vielzahl von Google Cloud Produkten verfügbar. Weitere Informationen finden Sie unter Node.js-Clientbibliotheken.

Bereitstellungsabhängigkeiten konfigurieren

Sie können Produktionsabhängigkeiten für NPM, Yarn oder Pnpm installieren:

NPM-Paketmanager

Wenn Sie Ihre Funktion bereitstellen, installiert Cloud Run-Funktionen die in der package.json Datei deklarierten Abhängigkeiten mit dem npm install Befehl:

npm install --production

Yarn-Paketmanager

Wenn in der Laufzeit von Node.js 8 und höher eine Datei yarn.lock vorhanden ist, verwendet Cloud Run-Funktionen stattdessen den yarn install Befehl:

yarn install --production

Pnpm-Paketmanager

Wenn in der Laufzeit von Node.js 8 und höher eine Datei pnpm-lock.yaml vorhanden ist, verwendet Cloud Run-Funktionen stattdessen den pnpm install Befehl:

pnpm install

Bun-Paketmanager

Vorschau – Unterstützung für den Bun-Paketmanager

Diese Funktion unterliegt den „Bedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA‑Funktionen stehen in der vorliegenden Form zur Verfügung und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie unter den Beschreibungen der Startphase.

Das Node.js-Buildpack unterstützt den Bun-Paketmanager. Mit dem Bun-Paketmanager können Sie Abhängigkeiten installieren und gleichzeitig die vorhandene Node.js-Projektstruktur und Laufzeitversion beibehalten. Sie können eine der folgenden Methoden auswählen, um Abhängigkeiten mit Bun zu installieren:

• Automatische Erkennung: Das Node.js-Buildpack erkennt den Bun-Paketmanager, wenn Sie eine Datei bun.lock oder bun.lockb in Ihr Projekt einfügen. So konfigurieren Sie die automatische Erkennung mit Bun:

  1. Erstellen Sie die Sperrdatei:

     bun install --lockfile-only
     

  2. Stellen Sie die Anwendung in Cloud Run bereit, indem Sie den folgenden Befehl ausführen:

      gcloud run deploy --source . --base-image=nodejs24
     

• Explizite Aktivierung: Legen Sie die Umgebungsvariable GOOGLE_PACKAGE_MANAGER auf bun fest. Bei dieser Methode müssen Sie keine Sperrdateien erstellen und verwalten. Führen Sie den folgenden Befehl aus, um die Anwendung in Cloud Run bereitzustellen:

  gcloud run deploy --source . --base-image=nodejs24 --set-build-env-vars GOOGLE_PACKAGE_MANAGER=bun
  

Während das Buildpack Bun zum Installieren von Abhängigkeiten verwendet, führt die Node.js-Laufzeit weiterhin Ihre Anwendung aus. Ihr Projekt muss eine Datei package.json enthalten. Weitere Informationen zu den Konfigurationsanforderungen finden Sie in der Buildpacks-Dokumentation unter Node.js-Anwendung erstellen.

Benutzerdefinierte Build-Schritte während der Bereitstellung ausführen

Nach der Bereitstellung können Sie während des Funktions-Build-Prozesses einen benutzerdefinierten Build-Schritt ausführen. Fügen Sie dazu ein gcp-build-Skript in die Datei package.json ein.

Wenn dieses Skript ausgeführt wird, sind die Abhängigkeiten in den Feldern dependencies und devDependencies der package.json-Datei verfügbar. Nach dem Ausführen des benutzerdefinierten Build-Schritts wird der Ordner node_modules von Cloud Run-Funktionen entfernt und neu generiert. Dies geschieht, indem genau die Produktionsabhängigkeiten installiert werden, die im Feld dependencies der package.json-Datei deklariert sind.

Wenn in package.json kein gcp-build-Skript vorhanden ist, installiert Cloud Run-Funktionen einfach Produktionsabhängigkeiten.

Systempakete verwenden

Die Node.js-Laufzeit enthält auch eine Reihe von Systempaketen in der Ausführungsumgebung.

Lokale Node.js-Module einschließen

Sie können auch lokale Node.js-Module in Ihre Funktion einbinden. Deklarieren Sie dazu Ihr Modul in package.json mit dem Präfix file:. Im folgenden Beispiel steht mymodule für den Modulnamen und mymoduledir für das Verzeichnis, in dem das Modul enthalten ist:

  {
  "dependencies": {
    "mymodule": "file:mymoduledir"
  }
}

Der Code für dieses lokale Modul sollte nicht im Ordner node_modules im Stammverzeichnis der Funktion gespeichert werden.

Hinweis: Wenn Sie die Bereitstellung mit dem gcloud-Befehlszeilentool durchführen, erstellt gcloud automatisch eine .gcloudignore-Datei im Verzeichnis Ihrer Funktion. Standardmäßig wird der Ordner node_modules dieser .gcloudignore-Datei hinzugefügt und nicht im Rahmen der Bereitstellung hochgeladen. Sie müssen den Ordner node_modules nicht einfügen, wenn Sie Code manuell als ZIP-Datei hochladen. Sie können die Funktion auch ohne den Ordner node_modules bereitstellen.

Node.js-Module laden

Verwenden Sie die Node.js-Funktion require(), um ein installiertes Node.js-Modul zu laden. Sie können auch die Funktion require() verwenden, um lokale Dateien zu importieren, die Sie gemeinsam mit der Funktion bereitstellen möchten.

Private Module verwenden

Sie können ein privates npm-Modul verwenden. Geben Sie dazu Einstellungen für die Authentifizierung mit der Registry in einer Datei .npmrc im Verzeichnis der Funktion an. Wenn Sie Yarn Version 2 oder höher als Paketmanager verwenden, heißt diese Datei .yarnrc.yml.

Private Module aus Artifact Registry

In einem Artifact Registry Node.js-Package Repository können private Module für Ihre Funktion gehostet werden. Wenn Sie eine Cloud Run-Funktion bereitstellen, generiert der Build-Prozess automatisch Artifact Registry-Anmeldedaten für das Cloud Build-Dienstkonto. Sie müssen nur das Artifact Registry-Repository in .npmrc auflisten, ohne zusätzliche Anmeldedaten zu generieren. Beispiel:

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

Dieser Ansatz kann auch für den Yarn v1-Paketmanager verwendet werden. Wenn Sie Yarn v2 oder höher verwenden, müssen Sie nur das Artifact Registry-Repository in .yarnrc.yml ohne zusätzliche Anmeldedaten auflisten. Beispiel:

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

Private Module aus anderen Repositories

Die npm-Dokumentation erläutert, wie benutzerdefinierte, schreibgeschützte Zugriffstoken erstellt werden. Wir raten davon ab, die im Basisverzeichnis erstellte .npmrc-Datei zu verwenden, da sie ein Lese-/Schreibtoken enthält. Schreibberechtigungen sind während der Bereitstellung nicht erforderlich und können ein Sicherheitsrisiko darstellen.

Fügen Sie die .npmrc-Datei nicht hinzu, wenn Sie keine privaten Repositories verwenden, da sie die Bereitstellungszeit für Ihre Funktionen erhöhen kann.

Hinweis: Wenn Sie benutzerdefinierte Berechtigungen verwenden (z. B. die für VPC erforderlichen Berechtigungen), müssen Sie Ihren Funktionen explizit erlauben, auf das private Ziel-Repository zuzugreifen.

Dateiformat

Wenn Sie eine .npmrc-Datei zum Festlegen eines benutzerdefinierten Auth-Tokens verwenden, sollte sie die folgende Zeile enthalten.

//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

Ersetzen Sie:

• REGISTRY_DOMAIN: der Domainname Ihrer privaten npm-Registry. Wenn Ihr Repository bei npmjs.org gehostet wird, legen Sie dieses Feld auf registry.npmjs.org fest.

• AUTH_TOKEN: das Autorisierungstoken für Ihre npm-Registry. Dies kann entweder der Literaltextwert des Tokens oder der Textstring ${NPM_TOKEN} sein, der npm durch den tatsächlichen Tokenwert aus der Umgebung ersetzt.

  Sie können die Umgebungsvariable $NPM_TOKEN mit dem Argument --set-build-env-vars auf den Befehl gcloud functions deploy festlegen. Weitere Informationen zum NPM-Authentifizierungstoken finden Sie in der NPM-Anleitung zu privaten Modulen.

Funktion mit kopierten Abhängigkeiten erstellen

Kopierte Abhängigkeiten sind Abhängigkeiten, deren Quelle direkt in Ihrem Quellcodepaket enthalten und zusammen mit Ihrem eigenen Code neu erstellt wird. Mit der Build-Umgebungsvariable GOOGLE_VENDOR_NPM_DEPENDENCIES erstellen Sie kopierte Node.js-Abhängigkeiten und überspringen die Installation während der Bereitstellung.

Voraussetzungen für kopierte Abhängigkeiten

1. Achten Sie darauf, dass Sie eine funktionierende Funktion haben, die alle Abhängigkeiten enthält, die Sie in der Datei package.json kopieren möchten.

2. Installieren Sie diese Abhängigkeiten lokal, indem Sie Folgendes ausführen:

       npm install
   

3. Entfernen Sie node_modules aus der Datei .gcloudignore in Ihrem Arbeitsverzeichnis.

4. Stellen Sie die Funktion bereit und achten Sie darauf, dass Ihre lokale Node.js-Version mit der Version übereinstimmt, die Sie während der Bereitstellung angeben.

5. Stellen Sie die Funktion und die kopierten Abhängigkeiten mit dem folgenden Befehl bereit:

     gcloud run deploy SERVICE \
       --source . \
       --function FUNCTION_ENTRY_POINT \
       --set-build-env-vars GOOGLE_VENDOR_NPM_DEPENDENCIES=true
   

   Ersetzen Sie:

   • SERVICE: der Name der Cloud Run-Funktion, die Sie bereitstellen
   • FUNCTION_ENTRY_POINT: der Einstiegspunkt zur Funktion in Ihrem Quellcode.

Wenn Sie in der Datei package.json eine npm-Engine angeben, wird die angegebene Version von npm zur Build-Zeit heruntergeladen. Entfernen Sie das Verhalten aus der Datei package.json, um dieses Verhalten zu unterdrücken.