Zum Inhalt

njs: NGINX njs dynamische Module

Installation

Sie können dieses Modul in jeder RHEL-basierten Distribution installieren, einschließlich, aber nicht beschränkt auf:

  • RedHat Enterprise Linux 7, 8, 9 und 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 und Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-njs

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-njs

Aktivieren Sie das Modul, indem Sie Folgendes an den Anfang von /etc/nginx/nginx.conf hinzufügen:

load_module modules/ngx_http_js_module.so;

load_module modules/ngx_stream_js_module.so;

Dieses Dokument beschreibt nginx-module-njs v0.9.6 veröffentlicht am 03. März 2026.

Projektstatus: Aktiv – Das Projekt hat einen stabilen, nutzbaren Zustand erreicht und wird aktiv weiterentwickelt. Community Support

NGINX JavaScript Banner

NGINX JavaScript

NGINX JavaScript, auch bekannt als NJS, ist ein dynamisches Modul für NGINX, das die Erweiterung der integrierten Funktionalität mit vertrauter JavaScript-Syntax ermöglicht. Die NJS-Sprache ist eine Teilmenge von JavaScript, die mit ES5 (ECMAScript 5.1 Strikte Variante) und einigen Erweiterungen von ES6 (ECMAScript 6) und neueren Versionen kompatibel ist. Weitere Details finden Sie unter Kompatibilität.

Wie es funktioniert

NGINX JavaScript wird als zwei dynamische Module für NGINX (ngx_http_js_module und ngx_stream_js_module) bereitgestellt und kann zu jeder unterstützten NGINX Open Source oder NGINX Plus Installation ohne Neukompilierung hinzugefügt werden.

Das NJS-Modul ermöglicht es NGINX-Administratoren: - Komplexe Zugriffssteuerungs- und Sicherheitsprüfungen durchzuführen, bevor Anfragen die Upstream-Server erreichen - Antwortheader zu manipulieren - Flexible, asynchrone Inhalts-Handler, Filter und mehr zu schreiben!

Siehe Beispiele und unsere verschiedenen Projekte, die mit NJS entwickelt wurden:

https://github.com/nginxinc/nginx-openid-connect

Erweitert die Funktionalität von NGINX Plus, um direkt mit OIDC-kompatiblen Identitätsanbietern zu kommunizieren, Benutzer zu authentifizieren und Inhalte zu autorisieren, die von NGINX Plus bereitgestellt werden.

https://github.com/nginxinc/nginx-saml

Referenzimplementierung von NGINX Plus als Dienstanbieter für SAML-Authentifizierung.

https://github.com/nginxinc/njs-prometheus-module

Stellt den Prometheus-Metriken-Endpunkt direkt von NGINX Plus bereit.

[!TIP] NJS kann auch mit dem NGINX Unit Anwendungserver verwendet werden. Erfahren Sie mehr über die Control API von NGINX Unit und wie Sie Funktionsaufrufe mit NJS definieren können.

Herunterladen und installieren

Befolgen Sie diese Schritte, um vorcompilierte NGINX- und NGINX JavaScript-Linux-Binärdateien herunterzuladen und zu installieren. Sie können auch wählen, das Modul lokal aus dem Quellcode zu erstellen.

Bereitstellung des NGINX-Paket-Repositorys

Befolgen Sie diese Anleitung, um das offizielle NGINX-Paket-Repository zu Ihrem System hinzuzufügen und NGINX Open Source zu installieren. Wenn Sie bereits NGINX Open Source oder NGINX Plus installiert haben, überspringen Sie den Installationsabschnitt für NGINX im letzten Schritt.

Erste Schritte mit NGINX JavaScript

Die Verwendung von NJS umfasst das Aktivieren des Moduls, das Hinzufügen von JavaScript-Dateien mit definierten Funktionen und das Aufrufen exportierter Funktionen in NGINX-Konfigurationsdateien.

Überprüfen, ob NGINX läuft

NGINX JavaScript ist ein Modul für NGINX Open Source oder NGINX Plus. Wenn Sie dies noch nicht getan haben, befolgen Sie diese Schritte, um NGINX Open Source oder NGINX Plus zu installieren. Stellen Sie nach der Installation sicher, dass die NGINX-Instanz läuft und auf HTTP-Anfragen reagieren kann.

NGINX starten

Geben Sie den folgenden Befehl ein, um NGINX zu starten:

sudo nginx

Überprüfen, ob NGINX auf HTTP-Anfragen reagiert

curl -I 127.0.0.1

Sie sollten die folgende Antwort sehen: 

HTTP/1.1 200 OK
Server: nginx/1.25.5

Aktivieren der NGINX JavaScript-Module

Sobald installiert, muss eines (oder beide) NJS-Module in die NGINX-Konfigurationsdatei aufgenommen werden. In den meisten Systemen befindet sich die NGINX-Konfigurationsdatei standardmäßig unter /etc/nginx/nginx.conf.

Bearbeiten der NGINX-Konfigurationsdatei

sudo vi /etc/nginx/nginx.conf

Dynamisches Laden der NJS-Module aktivieren

Verwenden Sie die load_module Direktive im obersten ("Haupt") Kontext, um eines (oder beide) Module zu aktivieren.

load_module modules/ngx_http_js_module.so;
load_module modules/ngx_stream_js_module.so;

Grundlagen des Schreibens von .js-Skriptdateien

NJS-Skriptdateien haben typischerweise die Endung .js und werden im Verzeichnis /etc/nginx/njs/ abgelegt. Sie bestehen normalerweise aus Funktionen, die dann exportiert werden, sodass sie in NGINX-Konfigurationsdateien verfügbar sind.

Referenz von benutzerdefinierten Objekten, Methoden und Eigenschaften

NJS bietet eine Sammlung von Objekten mit zugehörigen Methoden und Eigenschaften, die nicht Teil der ECMAScript-Definitionen sind. Siehe die vollständige Referenz zu diesen Objekten und wie sie verwendet werden können, um NGINX weiter zu erweitern und anzupassen.

Beispiel: Hallo Welt

Hier ist ein einfaches "Hallo Welt"-Beispiel.

example.js

Die hello-Funktion in dieser Datei gibt einen HTTP 200 OK-Statuscode zusammen mit dem String "Hello World!" zurück, gefolgt von einem Zeilenumbruch. Die Funktion wird dann für die Verwendung in einer NGINX-Konfigurationsdatei exportiert.

Fügen Sie diese Datei in das Verzeichnis /etc/nginx/njs ein:

function hello(r) {
  r.return(200, "Hello world!\n");
}

export default {hello}

nginx.conf

Wir ändern unsere NGINX-Konfiguration (/etc/nginx/nginx.conf), um die JavaScript-Datei zu importieren und die Funktion unter bestimmten Umständen auszuführen.

# Lade das ngx_http_js_module Modul
load_module modules/ngx_http_js_module.so;

events {}

http {
  # Setze den Pfad zu unseren njs JavaScript-Dateien
  js_path "/etc/nginx/njs/";

  # Importiere unsere JavaScript-Datei in die Variable "main"
  js_import main from http/hello.js;

  server {
    listen 80;

    location / {
      # Führe die "hello"-Funktion aus, die in unserer JavaScript-Datei definiert ist, bei allen HTTP-Anfragen
      # und antworte mit dem Inhalt unserer Funktion.
      js_content main.hello;
    }
  }
}

Für eine vollständige Liste der njs-Direktiven siehe die Dokumentationsseiten für ngx_http_js_module und ngx_stream_js_module.

[!TIP] Eine detailliertere Version dieses und anderer Beispiele finden Sie im offiziellen njs-examples-Repository.

Die NJS-Befehlszeilenschnittstelle (CLI)

NGINX JavaScript wird mit einem Dienstprogramm für die Befehlszeilenschnittstelle installiert. Die Schnittstelle kann als interaktive Shell geöffnet oder verwendet werden, um JavaScript-Syntax aus vordefinierten Dateien oder der Standardeingabe zu verarbeiten. Da das Dienstprogramm unabhängig läuft, sind NGINX-spezifische Objekte wie HTTP und Stream in seiner Laufzeit nicht verfügbar.

Beispiel für die Verwendung der interaktiven CLI

$ njs
>> globalThis
global {
  njs: njs {
    version: '0.8.4'
  },
  global: [Circular],
  process: process {
    argv: ['/usr/bin/njs'],
    env: {
      PATH: '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin',
      HOSTNAME: 'f777c149d4f8',
      TERM: 'xterm',
      NGINX_VERSION: '1.25.5',
      NJS_VERSION: '0.8.4',
      PKG_RELEASE: '1~buster',
      HOME: '/root'
    }
  },
  console: {
    log: [Function: native],
    dump: [Function: native],
    time: [Function: native],
    timeEnd: [Function: native]
  },
  print: [Function: native]
}
>>

Beispiel für die Verwendung der nicht-interaktiven CLI

$ echo "2**3" | njs -q
8

Klonen des NGINX JavaScript GitHub-Repositorys

Verwenden Sie Ihre bevorzugte Methode, um das NGINX JavaScript-Repository in Ihr Entwicklungsverzeichnis zu klonen. Siehe Klonen eines GitHub-Repositorys für zusätzliche Hilfe.

https://github.com/nginx/njs.git

Konfigurieren und Bauen

Führen Sie die folgenden Befehle im Stammverzeichnis Ihres geklonten Repositorys aus:

./configure

Bauen Sie NGINX JavaScript: 

make

Das Dienstprogramm sollte jetzt unter <NJS_SRC_ROOT_DIR>/build/njs verfügbar sein. Siehe Die NJS-Befehlszeilenschnittstelle (CLI) für Informationen zur Verwendung.

Klonen des NGINX GitHub-Repositorys

Klonen Sie das NGINX-Quellcode-Repository in ein Verzeichnis außerhalb des zuvor geklonten NJS-Quell-Repositorys.

https://github.com/nginx/nginx.git

NGINX JavaScript technische Spezifikationen

Die technischen Spezifikationen für NJS sind identisch mit denen von NGINX.

Unterstützte Distributionen

Siehe Getestete Betriebssysteme und Plattformen für eine vollständige Liste der unterstützten Distributionen.

Unterstützte Bereitstellungsumgebungen

  • Container
  • Öffentliche Cloud (AWS, Google Cloud Platform, Microsoft Azure)
  • Virtuelle Maschine

Unterstützte NGINX-Versionen

NGINX JavaScript wird von allen NGINX Open Source-Versionen unterstützt, die mit nginx-1.14 beginnen, und von allen NGINX Plus-Versionen, die mit NGINX Plus R15 beginnen.

Fragen stellen, Probleme melden und beitragen

Wir ermutigen Sie, sich mit uns in Verbindung zu setzen. Bitte sehen Sie sich die Beitragsrichtlinien an, um Informationen darüber zu erhalten, wie Sie Fragen stellen, Probleme melden und Code beitragen können.

Änderungsprotokoll

Siehe unsere Release-Seite, um Updates zu verfolgen.

GitHub

Sie finden möglicherweise zusätzliche Konfigurationstipps und Dokumentationen für dieses Modul im GitHub-Repository für nginx-module-njs.