nginx njs: Modul installieren, js_set einrichten und mit reload anwenden, um JavaScript-Variablen zu erstellen

Testumgebung RHEL-FamilieAlmaLinux 9.8Nginx 1.28 + Apache 2.4njs 0.9.4WP Rocket 3.23.5.1Geprüft am 2026-10-17

nginx njs ist ein offizielles nginx-Modul, das in der nginx-Konfiguration mit JavaScript-Funktionen Anfragen verarbeitet oder Variablenwerte erzeugt. Auf einem Server mit Nginx + Apache wurde – um die Groß- und Kleinschreibung von Anfrage-URLs anzugleichen, die sich mit der nginx-Konfiguration allein nicht ändern lässt – das njs-Modul in derselben Version wie das installierte nginx eingespielt, eine mit js_set erzeugte Variable in den Pfad der Cache-Datei eingesetzt und ohne Neustart per reload angewendet.

Die Beispielfunktion ist ein Einzeiler, der die Prozentkodierung koreanischer URLs kleinschreibt; Variablen aus Headern oder Argumenten des Request-Objekts zu bilden funktioniert genauso.

Inhalt

4 Min. Lesezeit

1️⃣ Was ist nginx njs: ein Modul, das nginx mit JavaScript erweitert

njs ist keine eigenständige JavaScript-Laufzeitumgebung wie Node.js: Es hat weder Startskript noch eigene Event-Loop, und der Code läuft nur, wenn nginx eine in der Konfiguration angegebene Funktion aufruft – danach geht die Verarbeitung an nginx zurück.

Die Stellen, an denen nginx JavaScript-Funktionen aufruft, sind festgelegt: die Verarbeitungsphasen von HTTP-Anfragen und -Antworten, die von TCP-/UDP-Sitzungen, die Berechnung von Variablenwerten und periodische Timer. Die Funktion liest URL, Header und Argumente aus dem Request-Objekt, das nginx übergibt, und gibt das Ergebnis als Antwort oder Variablenwert zurück.

Auf HTTP-Seite lädt [js_import] eine Skriptdatei, [js_set] erzeugt einen Variablenwert, [js_content] den Antwort-Body, und [js_header_filter] sowie [js_body_filter] bearbeiten Antwort-Header und -Body. Hier kamen zwei Direktiven zum Einsatz: [js_import] und [js_set].

🧭 Wo nginx njs-Funktionen aufruft

Erklär-Diagramm

📌 Aufrufstelle

📥 Anfrage

🖥️ nginx

Verarbeitungsphase · in der Konfiguration festgelegte Stelle

js_setBerechnung des Variablenwerts

js_contentAntwort-Body

js_header_filter · js_body_filterAntwort-Header · Body bearbeiten

Aufruf→

📜 njs-Funktion

Von nginx übergebenes Request-Objekt

URL · Header · Argumente lesen

↩️ Rückgabe als Variablenwert

↩️ Rückgabe als Antwort

↩️ Rückgabe als bearbeitete Header · Body

❌ Läuft nicht eigenständig wie Node.jsKein Startskript · keine eigene Event-Loop

Rückgabe→

🖥️ nginx

Verarbeitet weiter

VariablenwertHier eingesetzt · im Pfad der Cache-Datei

Antwort-BodyAntwortet mit dem von der Funktion erzeugten Body

Antwort-Header · BodyAntwortet mit den bearbeiteten Headern und dem Body

📤 Antwort

[js_set] ruft die Funktion an der Stelle auf, an der nginx einen Variablenwert berechnet; der Rückgabewert der Funktion wird zum Variablenwert, und die Verarbeitung geht an nginx zurück.

[js_content] ruft die Funktion an der Stelle auf, an der der Antwort-Body entsteht, und nginx sendet die Antwort, die die Funktion aus dem Request-Objekt gebaut hat.

[js_header_filter] und [js_body_filter] rufen die Funktion beim Ausliefern der Antwort auf, um Header und Body zu bearbeiten; danach geht die Verarbeitung an nginx zurück.

Die Standard-Engine des njs-Moduls implementiert ECMAScript 5.1 (strict mode) plus einige Funktionen ab ECMAScript 6. Zeichenkettenverarbeitung auf dem Niveau von Regex-Ersetzungen und Funktionen funktioniert in diesem Rahmen.

2️⃣ Wann njs nötig ist: Variablenwerte, die die nginx-Konfiguration allein nicht ändern kann

Das WordPress-Plugin WP Rocket benennt die Cache-Ordner von Beiträgen mit koreanischen URLs in kleingeschriebener Prozentkodierung, Browser fragen dieselbe URL dagegen großgeschrieben kodiert an. Auf diesem Server läuft eine WordPress-Website.

Baut nginx den Pfad der Cache-Datei aus der Anfrage-URL, wie sie ist, passt die Groß- und Kleinschreibung nicht, die Datei wird nicht gefunden, und die Anfrage geht an Apache und PHP.

Mit der nginx-Konfiguration allein lässt sich dieser Wert nicht kleinschreiben. [map] wählt nur einen der festgelegten Werte aus und kann keine Zeichenketten umwandeln, und vor der Installation zeigten weder die Ausgabe von [nginx -V] noch der Modulordner ein perl- oder lua-Modul.

Sind nur wenige URLs umzustellen, reicht eine [map]-Zuordnungstabelle – nur muss sie bei jedem neuen Beitrag neu erstellt und per reload geladen werden. Braucht jede URL ihren eigenen, nach derselben Regel umgewandelten Wert, deckt eine einzige [js_set]-Funktion auch neue Beiträge, Tags und Kategorie-URLs ab.

🧭 WP Rocket und koreanische URLs

[perl_set] aus dem perl-Modul lässt sich an derselben Stelle einsetzen, und im Repository gibt es ein zu nginx passendes Paket – die offizielle nginx-Dokumentation führt das perl-Modul aber als experimentell.

3️⃣ nginx njs installieren: in derselben Version wie das installierte nginx

Installiert man nur über den Paketnamen, sieht es so aus, als käme nur njs dazu – doch das neueste njs im Repository verlangt das neueste nginx, also wird nginx gleich mit aktualisiert. Bei der Prüfung vor der Installation zeigte der Installationsbefehl ohne Versionsangabe den Plan, nginx von 1.28.0 auf 1.30.6 zu heben.

Deshalb prüfst du zuerst die installierte nginx-Version.

rpm -q nginx

nginx-1.28.0-1.el9.ngx.x86_64

Im Repository gibt es zu jeder nginx-Version ein eigenes passendes njs-Paket; in der Versionsnummer steht vor dem + die nginx-Version, dahinter die njs-Version.

dnf list --showduplicates nginx-module-njs | grep '1.28.0+'

nginx-module-njs.x86_64         1:1.28.0+0.9.4-1.el9.ngx           @nginx-stable
nginx-module-njs.x86_64         1:1.28.0+0.8.10-1.el9.ngx          nginx-stable
nginx-module-njs.x86_64         1:1.28.0+0.9.0-1.el9.ngx           nginx-stable
nginx-module-njs.x86_64         1:1.28.0+0.9.1-1.el9.ngx           nginx-stable
nginx-module-njs.x86_64         1:1.28.0+0.9.2-1.el9.ngx           nginx-stable
nginx-module-njs.x86_64         1:1.28.0+0.9.3-1.el9.ngx           nginx-stable
nginx-module-njs.x86_64         1:1.28.0+0.9.4-1.el9.ngx           nginx-stable

Zu nginx 1.28.0 passen sechs Versionen von 0.8.10 bis 0.9.4; die oberste @nginx-stable-Zeile ist die bereits installierte. Installiert wird die neueste davon, 0.9.4, mit vollständiger Versionsnummer.

dnf install nginx-module-njs-1:1.28.0+0.9.4-1.el9.ngx

Welche nginx-Version das installierte Paket verlangt, zeigt rpm.

rpm -q --requires nginx-module-njs | grep nginx

nginx-r1.28.0

rpm -ql nginx-module-njs | grep -v build-id

/usr/bin/njs
/usr/lib64/nginx/modules/ngx_http_js_module-debug.so
/usr/lib64/nginx/modules/ngx_http_js_module.so
/usr/lib64/nginx/modules/ngx_stream_js_module-debug.so
/usr/lib64/nginx/modules/ngx_stream_js_module.so
/usr/share/doc/nginx-module-njs
/usr/share/doc/nginx-module-njs/CHANGES
/usr/share/doc/nginx-module-njs/COPYRIGHT

Installiert wurden das HTTP-Modul, das stream-Modul für TCP/UDP, je eine Debug-Version und das Kommandozeilen-Tool njs. Diese Konfiguration lädt nur eine Datei, das HTTP-Modul [ngx_http_js_module.so].

4️⃣ js_set einrichten: vom Laden des Moduls bis zum Pfad der Cache-Datei

Das Installieren des Pakets bringt nginx nicht dazu, das Modul automatisch zu laden; ganz oben in der nginx.conf muss eine [load_module]-Zeile stehen. Laut offizieller Dokumentation ist [load_module] eine Direktive des main-Kontexts und steht daher außerhalb der events- und http-Blöcke.

📂 /etc/nginx/Konfigurationsordner

nginx.confload_module ganz oben — lädt das Modul

njs/rocket.jsFunktion lc — nur die Prozentkodierung kleinschreiben

conf.d/

rocket-njs.confhttp-Block — js_import · js_set

example.com.confserver-Block — $rocket_uri im Pfad der Cache-Datei

# ganz oben in /etc/nginx/nginx.conf (außerhalb der events- und http-Blöcke)
load_module modules/ngx_http_js_module.so;

Die Umwandlungsfunktion liegt getrennt von den Konfigurationsdateien in einer .js-Datei, und die nginx-Konfiguration importiert die in der letzten Zeile mit export default exportierte Funktion.

// /etc/nginx/njs/rocket.js — nur die Prozentkodierung %XX kleinschreiben
function lc(r) {
    return r.variables.request_uri.replace(/%[0-9A-F]{2}/g, function (m) { return m.toLowerCase(); });
}
export default { lc };

Die Funktion liest die Variable [request_uri] aus dem Request-Objekt r, schreibt nur die zwei Zeichen nach jedem Prozentzeichen klein, sofern sie großgeschrieben sind, und gibt das Ergebnis zurück. Lateinische Buchstaben bleiben unverändert, englische URLs mit Großbuchstaben ändern sich also nicht – das entspricht der Regel, nach der WP Rocket Cache-Ordner benennt.

# im http-Block (eine .conf-Datei in conf.d)
js_import rkt from /etc/nginx/njs/rocket.js;
js_set $rocket_uri rkt.lc;

In [js_import] ist rkt der Name, über den Funktionen im Modul aufgerufen werden, und [js_set] macht aus dem Ergebnis dieser Funktion die Variable [$rocket_uri]. Laut offizieller Dokumentation läuft die Funktion, wenn die Variable in einer Anfrage zum ersten Mal referenziert wird, und unterstützt nur synchrone Verarbeitung.

# server-Block — $request_uri im Pfad der Cache-Datei wird zu $rocket_uri
set $rocket_file '/wp-content/cache/wp-rocket/example.com${rocket_uri}index$rocket_mobile-https.html';

Geändert wurde nur diese eine Zeile, die den Pfad der Cache-Datei baut; die Prüfungen, die Login-Cookies, Query-Strings und POST-Anfragen vom Cache ausnehmen, bleiben, wie sie sind.

5️⃣ Anwenden und prüfen: Fehlerlog und Antwort-Header nach dem reload

Führe zuerst den Konfigurationstest aus und lade bei Erfolg per reload neu.

nginx -t

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

systemctl reload nginx

Die neue [load_module]-Zeile wurde ohne Neustart per reload übernommen. Im Fehlerlog stand eine Zeile zur Initialisierung der virtuellen njs-Maschine, JavaScript-Fehler gab es keine.

grep 'js vm init' /var/log/nginx/error.log | head -1

2026/10/17 18:21:35 [notice] 27992#27992: js vm init njs: 0000559FDF6D0E00

Das njs am Zeilenende ist der Name der verwendeten Engine. Dieselbe Zeile wird auch beim Konfigurationstest mit [nginx -t] geschrieben – gleiche sie daher mit der Uhrzeit des reload ab.

curl -sI 'https://example.com/-/' | grep -i 'x-rocket\|content-type'

content-type: text/html
x-rocket-nginx-serving-file: HIT

Auch bei einer großgeschrieben kodierten koreanischen URL kam der Header, der die Auslieferung der Cache-Datei durch nginx anzeigt. Anfragen mit Query-String oder Login-Cookie sowie POST-Anfragen gingen auch nach der Änderung ohne diesen Header an PHP.

6️⃣ njs zurücknehmen und nginx aktualisieren

Zum Zurücknehmen setzt du im Pfad der Cache-Datei [$rocket_uri] wieder auf [$request_uri], entfernst die Konfigurationsdatei mit [js_import]/[js_set] und die [load_module]-Zeile, testest die Konfiguration und lädst per reload neu.

# server-Block — zurück zur ursprünglichen Variable
set $rocket_file '/wp-content/cache/wp-rocket/example.com${request_uri}index$rocket_mobile-https.html';

Das Paket kann installiert bleiben: Ohne [load_module]-Zeile lädt nginx es nicht; entferne das Paket nur, wenn es ganz weg soll.

dnf remove nginx-module-njs

Beim Aktualisieren von nginx muss das njs-Paket mit auf die zur neuen nginx-Version passende Version. Prüfe vorher mit [dnf list --showduplicates], ob das Repository das passende njs zur neuen nginx-Version hat.

🔢 FAQ & empfohlene Inhalte

Die offizielle nginx-Dokumentation führt die Standard-njs-Engine ab Version 1.0.0 als veraltet (deprecated) und empfiehlt für neue Setups die QuickJS-Engine mit ES2023-Unterstützung. Die Engine wählst du mit der Direktive [js_engine qjs], die es seit 0.8.6 gibt. Die 0.9.4-Installation in diesem Artikel lief mit der Standard-njs-Engine; ein Wechsel zu QuickJS wurde nicht getestet.

Es ist ein eigenständiges Kommandozeilen-Tool, um njs-Code ohne nginx zu entwickeln und zu debuggen (laut offizieller Dokumentation). Es kommt mit dem Paket nginx-module-njs, und [njs -v] zeigt dieselbe Version 0.9.4 wie das Modul.

Verarbeitest du nur HTTP-Anfragen, genügt [ngx_http_js_module]. Das Paket enthält auch [ngx_stream_js_module] für TCP-/UDP-Sitzungen, und die offizielle Installationsanleitung sagt, das jeweils benötigte der beiden Module mit [load_module] zu laden.

🧭 WP Rocket·Perfmatters – verwandte Beiträge 15 Beiträge · 3 Tools

🗂️ Was ist WP?

📋 WP Rocket Anleitung 📄 Perfmatters Anleitung 📄 WP Rocket With Perfmatters 📄 WP Rocket MCP Server 📄 WP Rocket mit koreanischen URLs 📄 nginx njs 📄 WP Rocket mehrsprachiger Cache 📄 gclid-Cache

📄 WP Rocket Speedtest 📝 Cache- und Optimierungs-Plugins 📝 Beispiele für mehr Tempo

📋 Cache: Definition und alle Bereiche 📄 Website-Cache & serverseitiger Cache

📋 BEST Hosting TOP 7 📄 Schnelles Hosting 2026

🛠️ WordPress Theme Detector 🛠️ Whois-Domainabfrage 🛠️ Meine IP prüfen