nginx njs: installare il modulo, impostare js_set e applicare con reload per creare variabili JavaScript

Ambiente di test Famiglia RHELAlmaLinux 9.8Nginx 1.28 + Apache 2.4njs 0.9.4WP Rocket 3.23.5.1Controllato il 17/10/2026

nginx njs è un modulo ufficiale di nginx che gestisce le richieste o crea valori di variabili con funzioni JavaScript dentro la configurazione di nginx. Su un server con Nginx + Apache, per allineare maiuscole e minuscole degli URL richiesti, cosa che la sola configurazione di nginx non può cambiare, il modulo njs è stato installato nella stessa versione del nginx installato, e una variabile creata con js_set è stata messa nel percorso del file di cache e applicata con un reload, senza riavvio.

La funzione d'esempio è una riga sola che porta in minuscolo la codifica percentuale degli URL coreani, e creare variabili leggendo intestazioni o valori di argomenti dall'oggetto della richiesta funziona allo stesso modo.

Indice

4 min di lettura

1️⃣ Cos'è nginx njs: un modulo che estende nginx con JavaScript

njs non è un runtime JavaScript autonomo come Node.js: non ha uno script di avvio né un event loop proprio, e il codice gira solo quando nginx chiama una funzione indicata nella configurazione, dopodiché l'elaborazione torna a nginx.

I punti in cui nginx chiama le funzioni JavaScript sono fissi: le fasi di elaborazione delle richieste e risposte HTTP, le fasi di elaborazione delle sessioni TCP/UDP, il calcolo dei valori delle variabili e i timer periodici. La funzione legge URL, intestazioni e argomenti dall'oggetto della richiesta passato da nginx e restituisce il risultato come risposta o come valore di variabile.

Sul lato HTTP, [js_import] carica un file di script, [js_set] crea un valore di variabile, [js_content] crea il corpo della risposta, e [js_header_filter] e [js_body_filter] modificano intestazioni e corpo della risposta. Questa configurazione ha usato due direttive: [js_import] e [js_set].

🧭 Dove nginx chiama le funzioni njs

Diagramma esplicativo

📌 Punto di chiamata

📥 Richiesta

🖥️ nginx

Fase di elaborazione · punto indicato nella configurazione

js_setCalcolo del valore della variabile

js_contentCorpo della risposta

js_header_filter · js_body_filterModifica di intestazioni · corpo della risposta

Chiamata→

📜 Funzione njs

Oggetto della richiesta passato da nginx

Lettura di URL · intestazioni · argomenti

↩️ Restituito come valore di variabile

↩️ Restituito come risposta

↩️ Restituito come intestazioni · corpo modificati

❌ Non gira da solo come Node.jsNessuno script di avvio · nessun event loop proprio

Ritorno→

🖥️ nginx

Prosegue l'elaborazione

Valore della variabileUsato qui · inserito nel percorso del file di cache

Corpo della rispostaRisponde con il corpo creato dalla funzione

Intestazioni · corpo della rispostaRisponde con intestazioni e corpo modificati

📤 Risposta

[js_set] chiama la funzione nel punto in cui nginx calcola un valore di variabile; il valore restituito dalla funzione diventa il valore della variabile e l'elaborazione torna a nginx.

[js_content] chiama la funzione nel punto in cui si crea il corpo della risposta, e nginx invia la risposta che la funzione ha costruito dall'oggetto della richiesta.

[js_header_filter] e [js_body_filter] chiamano la funzione mentre la risposta viene inviata per modificarne intestazioni e corpo e, finito questo, l'elaborazione torna a nginx.

Il motore predefinito del modulo njs implementa ECMAScript 5.1 (strict mode) più alcune funzionalità di ECMAScript 6 e successivi. L'elaborazione di stringhe a livello di sostituzione con regex e funzioni funziona entro questo ambito.

2️⃣ Quando serve njs: valori di variabili che la sola configurazione di nginx non può cambiare

Il plugin WordPress WP Rocket dà alle cartelle di cache degli articoli con URL coreani nomi in codifica percentuale minuscola, mentre i browser richiedono lo stesso URL codificato in maiuscolo. Su questo server gira un sito WordPress.

Se nginx costruisce il percorso del file di cache dall'URL della richiesta così com'è, maiuscole e minuscole non coincidono, il file non viene trovato e la richiesta passa ad Apache e PHP.

Con la sola configurazione di nginx non puoi portare questo valore in minuscolo. [map] sceglie solo uno dei valori che imposti e non trasforma stringhe, e prima dell'installazione né l'output di [nginx -V] né la cartella dei moduli mostravano un modulo perl o lua.

Se devono cambiare solo pochi URL, basta una tabella [map], ma devi rifare la tabella e fare reload ogni volta che esce un nuovo articolo. Quando ogni URL deve avere il proprio valore convertito con la stessa regola, una sola funzione [js_set] copre anche nuovi articoli, tag e URL delle categorie.

🧭 WP Rocket e URL coreani

Anche [perl_set] del modulo perl si può usare nello stesso punto, e il repository ha un pacchetto abbinato a nginx, ma la documentazione ufficiale di nginx descrive il modulo perl come sperimentale.

3️⃣ Installare nginx njs: nella stessa versione del nginx installato

Installare con il solo nome del pacchetto sembra aggiungere solo njs, ma il njs più recente del repository richiede il nginx più recente, quindi viene aggiornato anche nginx. Nel controllo prima dell'installazione, il comando senza versione ha mostrato un piano per portare nginx da 1.28.0 a 1.30.6.

Quindi parti dal controllare la versione di nginx installata ora.

rpm -q nginx

nginx-1.28.0-1.el9.ngx.x86_64

Il repository ha un pacchetto njs separato abbinato a ogni versione di nginx; nel numero di versione la parte prima del + è la versione di nginx e quella dopo è la versione di njs.

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

Sei versioni, da 0.8.10 a 0.9.4, sono abbinate a nginx 1.28.0, e la riga @nginx-stable in cima è quella già installata. Installa la più recente, 0.9.4, scrivendo il numero di versione completo.

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

Con rpm puoi controllare quale versione di nginx richiede il pacchetto installato.

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

I file installati sono il modulo HTTP, il modulo stream che gestisce TCP/UDP, una build di debug di ciascuno e lo strumento da riga di comando njs. Questa configurazione carica un solo file, il modulo HTTP [ngx_http_js_module.so].

4️⃣ Impostare js_set: dal caricamento del modulo al percorso del file di cache

Installare il pacchetto non fa caricare il modulo a nginx in automatico: nginx.conf ha bisogno di una riga [load_module] in cima. Secondo la documentazione ufficiale, [load_module] è una direttiva del contesto main, quindi va fuori dai blocchi events e http.

📂 /etc/nginx/Cartella di configurazione

nginx.confload_module in cima — carica il modulo

njs/rocket.jsFunzione lc — solo la codifica percentuale in minuscolo

conf.d/

rocket-njs.confblocco http — js_import · js_set

example.com.confblocco server — $rocket_uri nel percorso del file di cache

# in cima a /etc/nginx/nginx.conf (fuori dai blocchi events e http)
load_module modules/ngx_http_js_module.so;

La funzione di conversione sta in un file .js separato dai file di configurazione, e la configurazione di nginx importa la funzione esportata con export default nell'ultima riga.

// /etc/nginx/njs/rocket.js — solo la codifica percentuale %XX in minuscolo
function lc(r) {
    return r.variables.request_uri.replace(/%[0-9A-F]{2}/g, function (m) { return m.toLowerCase(); });
}
export default { lc };

La funzione legge la variabile [request_uri] dall'oggetto della richiesta r, porta in minuscolo solo i due caratteri dopo ogni segno di percentuale dove sono maiuscoli e restituisce il risultato. Le lettere latine restano come sono, quindi gli URL inglesi con maiuscole non cambiano; è la stessa regola che WP Rocket usa per nominare le cartelle di cache.

# dentro il blocco http (un file .conf in conf.d)
js_import rkt from /etc/nginx/njs/rocket.js;
js_set $rocket_uri rkt.lc;

In [js_import], rkt è il nome con cui si chiamano le funzioni del modulo, e [js_set] trasforma il risultato di quella funzione nella variabile [$rocket_uri]. Secondo la documentazione ufficiale, la funzione viene eseguita quando la variabile è usata per la prima volta in una richiesta e supporta solo l'elaborazione sincrona.

# blocco server — $request_uri nel percorso del file di cache diventa $rocket_uri
set $rocket_file '/wp-content/cache/wp-rocket/example.com${rocket_uri}index$rocket_mobile-https.html';

L'unica modifica è questa riga che costruisce il percorso del file di cache; i controlli che escludono dalla cache cookie di login, query e richieste POST restano come sono.

5️⃣ Applicare e verificare: log degli errori e intestazioni di risposta dopo il reload

Esegui prima il test della configurazione e, se passa, fai il reload.

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

La nuova riga [load_module] è entrata in vigore con un reload, senza riavvio. Il log degli errori ha registrato una riga sull'inizializzazione della macchina virtuale njs e non c'erano errori JavaScript.

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

Il njs alla fine della riga è il nome del motore in uso. La stessa riga viene registrata anche quando testi la configurazione con [nginx -t], quindi confrontala con l'ora del reload.

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

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

Anche per un URL coreano codificato in maiuscolo c'era l'intestazione che indica che nginx ha servito il file di cache. Le richieste con query o cookie di login e le richieste POST sono andate ancora a PHP senza quell'intestazione dopo la modifica.

6️⃣ Annullare njs e aggiornare nginx

Per tornare indietro, rimetti [$request_uri] al posto di [$rocket_uri] nel percorso del file di cache, togli il file di configurazione con [js_import]/[js_set] e la riga [load_module], poi esegui il test della configurazione e fai il reload.

# blocco server — di nuovo alla variabile originale
set $rocket_file '/wp-content/cache/wp-rocket/example.com${request_uri}index$rocket_mobile-https.html';

Puoi lasciare installato il pacchetto: senza la riga [load_module] nginx non lo carica, quindi rimuovi il pacchetto solo se vuoi toglierlo del tutto.

dnf remove nginx-module-njs

Quando aggiorni nginx, anche il pacchetto njs deve salire alla versione abbinata al nuovo nginx. Prima di aggiornare, controlla con [dnf list --showduplicates] che il repository abbia il njs corrispondente alla nuova versione di nginx.

🔢 FAQ & contenuti consigliati

La documentazione ufficiale di nginx segna il motore njs predefinito come deprecato (deprecated) dalla versione 1.0.0 e consiglia per le nuove configurazioni il motore QuickJS, che supporta ES2023. Il motore si sceglie con la direttiva [js_engine qjs], disponibile dalla versione 0.8.6. L'installazione 0.9.4 di questo articolo ha usato il motore njs predefinito, e il passaggio a QuickJS non è stato provato.

È uno strumento da riga di comando autonomo per sviluppare e fare il debug di codice njs senza nginx (secondo la documentazione ufficiale). Arriva con il pacchetto nginx-module-njs, e controllando la versione con [njs -v] compare 0.9.4, la stessa del modulo.

Se gestisci solo richieste HTTP, basta [ngx_http_js_module]. Il pacchetto include anche [ngx_stream_js_module] per le sessioni TCP/UDP, e la documentazione ufficiale di installazione dice di caricare con [load_module] quello dei due che ti serve.

🧭 Articoli su WP Rocket 16 articoli · 3 strumenti

🗂️ Cos'è WP?

📋 Guida alle impostazioni di WP Rocket 📄 WP Rocket MCP Server 📄 WP Rocket e URL in coreano 📄 nginx njs 📄 Cache multilingue di WP Rocket 📄 Cache e gclid

📄 Test di velocità di WP Rocket 📝 Plugin di cache e ottimizzazione 📝 Un caso di miglioramento della velocità

📋 Cache: definizione e tutti gli ambiti 📄 Cache del sito web & cache interna del server

📋 Migliori hosting: TOP 7 📄 Hosting veloce 2026

🛠️ Rileva WordPress 🛠️ Ricerca WHOIS 🛠️ Qual è il mio IP

WordPress · Perfmatters

WP Rocket With Perfmatters: come usarli insieme e guida alle impostazioni di ottimizzazione

Come configurare WP Rocket e Perfmatters quando li usi insieme.