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. Cloud Run-Funktions-Node.js-Laufzeiten unterstützen die Installation mit npm, yarn oder pnpm.

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

Hinweis: Wenn eine package-lock.json-, yarn.lock- oder pnpm-lock.yaml-Datei in Ihrem Projekt gefunden wird, wird diese Sperrdatei bei der Installation von Abhängigkeiten mit npm ci, yarn install oder pnpm install berücksichtigt.

In diesem Beispiel ist eine Abhängigkeit in der Datei package.json enthalten:

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

Die Abhängigkeit wird dann in die Funktion importiert:

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')}!`);
});

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

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

Node.js-Module mit npm lokal 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 uuid-Modul 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 node_modules-Verzeichnis 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. Eine Liste finden Sie hier.

Bereitstellungsabhängigkeiten konfigurieren

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

NPM

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

npm install --production

Yarn

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

yarn install --production

Pnpm

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

pnpm install

Hinweis: In Unterverzeichnissen deklarierte Abhängigkeiten werden nicht installiert. Wenn Sie ein Monorepo verwenden, können Sie während der Bereitstellung ein benutzerdefiniertes Build-Skript ausführen, um diese Abhängigkeiten zu installieren.

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. Wenn die Funktion eine Abhängigkeit verwendet, für die ein nicht aufgeführtes Paket erforderlich ist, können Sie ein Paket anfordern.

Hinweis: Sie können auch containerisierte Versionen Ihrer Cloud Run-Node.js-Funktion mithilfe des Functions Framework für Cloud Run bereitstellen.

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 .npmrc-Datei 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. Beispiele:

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 es die unten aufgeführte 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 Anbieterabhängigkeiten erstellen

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

Voraussetzungen für übernommene Abhängigkeiten

1. Achten Sie darauf, dass Sie eine funktionierende Funktion haben, die alle Abhängigkeiten enthält, die der Anbieter in der Datei package.json definiert hat.

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

       npm install
   

3. Entfernen Sie node_modules aus der .gcloudignore-Datei 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 Anbieterabhängigkeiten mit dem folgenden Befehl bereit:

     gcloud functions deploy FUNCTION_NAME \
       --runtime RUNTIME_NAME \
       --set-build-env-vars GOOGLE_VENDOR_NPM_DEPENDENCIES=true
   

   Ersetzen Sie:

   • FUNCTION_NAME: der Name der Cloud Run-Funktion, die Sie bereitstellen
   • RUNTIME_NAME ist der Name der Node.js-Laufzeit, in der die bereitgestellte Funktion ausgeführt werden soll. Dies muss dieselbe Node.js-Version sein, die Sie in Ihrer lokalen Entwicklungsumgebung verwendet haben.

Das Functions Framework-Paket ist eine erforderliche Abhängigkeit für Funktionen. Für schnellere Builds empfehlen wir die Verwendung dieses Pakets. Ist dies nicht der Fall, wird sie heruntergeladen und installiert, wenn die Funktion erstellt wird.

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 package.json-Datei, um dieses Verhalten zu unterdrücken.