nginx njs: Modülü kurma, js_set ayarlama ve reload ile uygulayarak JavaScript değişkenleri oluşturma

Test ortamı RHEL ailesiAlmaLinux 9.8Nginx 1.28 + Apache 2.4njs 0.9.4WP Rocket 3.23.5.117.10.2026 tarihinde kontrol edildi

nginx njs, nginx yapılandırması içinde JavaScript işlevleriyle istekleri işleyen ya da değişken değerleri oluşturan resmî bir nginx modülüdür. Nginx + Apache yapılandırmalı bir sunucuda, yalnızca nginx ayarıyla değiştirilemeyen istek adreslerindeki büyük-küçük harfi eşitlemek için njs modülü kurulu nginx ile aynı sürümde kuruldu, js_set ile oluşturulan değişken önbellek dosyası yoluna kondu ve yeniden başlatmadan reload ile uygulandı.

Örnek işlev, Korece adreslerin yüzde kodlamasını küçük harfe çeviren tek satırlık bir işlevdir; istek nesnesinden başlık ya da argüman değerlerini okuyup değişken oluşturmak da aynı şekilde çalışır.

İçindekiler

4 dk okuma

1️⃣ nginx njs nedir: nginx'i JavaScript ile genişleten modül

njs, Node.js gibi tek başına çalışan bir JavaScript çalışma ortamı değildir; başlangıç betiği ya da kendi olay döngüsü yoktur, kod yalnızca nginx ayarda belirtilen bir işlevi çağırdığında çalışır ve ardından işlem nginx'e döner.

nginx'in JavaScript işlevlerini çağırdığı yerler bellidir: HTTP istek ve yanıt işleme aşamaları, TCP/UDP oturum işleme aşamaları, değişken değeri hesaplama ve periyodik zamanlayıcılar. İşlev, nginx'in verdiği istek nesnesinden adresi, başlıkları ve argümanları okur, sonucu yanıt ya da değişken değeri olarak döndürür.

HTTP tarafında [js_import] betik dosyasını yükler, [js_set] değişken değeri oluşturur, [js_content] yanıt gövdesini oluşturur, [js_header_filter] ve [js_body_filter] yanıt başlıklarını ve gövdesini düzenler. Bu uygulamada iki yönerge kullanıldı: [js_import] ve [js_set].

🧭 nginx'in njs işlevlerini çağırdığı yerler

Açıklama diyagramı

📌 Çağrı noktası

📥 İstek

🖥️ nginx

İşleme aşaması · ayarda belirtilen nokta

js_setDeğişken değeri hesaplama

js_contentYanıt gövdesi

js_header_filter · js_body_filterYanıt başlıklarını · gövdesini düzenleme

Çağrı→

📜 njs işlevi

nginx'in verdiği istek nesnesi

Adres · başlık · argüman okuma

↩️ Değişken değeri olarak döner

↩️ Yanıt olarak döner

↩️ Düzenlenmiş başlık · gövde olarak döner

❌ Node.js gibi tek başına çalışmazBaşlangıç betiği yok · kendi olay döngüsü yok

Dönüş→

🖥️ nginx

İşleme devam eder

Değişken değeriBu uygulamada · önbellek dosyası yoluna kondu

Yanıt gövdesiİşlevin oluşturduğu gövdeyle yanıt

Yanıt başlıkları · gövdesiDüzenlenmiş başlık ve gövdeyle yanıt

📤 Yanıt

[js_set], nginx'in değişken değerini hesapladığı noktada işlevi çağırır; işlevin döndürdüğü değer değişken değeri olur ve işlem nginx'e döner.

[js_content], yanıt gövdesinin oluşturulduğu noktada işlevi çağırır; işlevin istek nesnesinden oluşturduğu yanıtı nginx gönderir.

[js_header_filter] ve [js_body_filter], yanıt gönderilirken işlevi çağırıp başlıkları ve gövdeyi düzenler; düzenleme bitince işlem nginx'e döner.

njs modülünün varsayılan motoru ECMAScript 5.1'i (strict mode) ve ECMAScript 6 ile sonrasının bazı özelliklerini uygular. Düzenli ifadeyle değiştirme ve işlev düzeyindeki metin işlemleri bu kapsamda çalışır.

2️⃣ njs ne zaman gerekir: Yalnızca nginx ayarıyla değiştirilemeyen değişken değerleri

WordPress eklentisi WP Rocket, Korece adresli yazıların önbellek klasörü adlarını küçük harfli yüzde kodlamasıyla oluşturur; tarayıcılar ise aynı adresi büyük harfle kodlayarak ister. Bu sunucuda bir WordPress sitesi çalışıyor.

nginx önbellek dosyası yolunu istek adresinden olduğu gibi oluşturursa büyük-küçük harf uyuşmaz, dosya bulunamaz ve istek Apache ile PHP'ye geçer.

Yalnızca nginx ayarıyla bu değer küçük harfe çevrilemez. [map] yalnızca tanımladığınız değerlerden birini seçer, metni dönüştüremez; kurulumdan önce [nginx -V] çıktısında ve modül klasöründe perl ya da lua modülü de yoktu.

Değişecek yalnızca birkaç adres varsa [map] eşleme tablosu da iş görür, ama her yeni yazıda tabloyu yeniden yapıp reload etmeniz gerekir. Her adresin farklı değerini aynı kuralla değiştirmek gerekiyorsa tek bir [js_set] işlevi yeni yazıları, etiketleri ve kategori adreslerini de kapsar.

🧭 WP Rocket ve Korece URL'ler

perl modülünün [perl_set] yönergesi de aynı yerde kullanılabilir ve depoda nginx ile eşleşen bir paket vardır, ama resmî nginx belgeleri perl modülünü deneysel olarak tanımlar.

3️⃣ nginx njs kurulumu: Kurulu nginx ile aynı sürümde

Yalnızca paket adıyla kurmak sadece njs ekleyecekmiş gibi görünür, ama depodaki en yeni njs en yeni nginx'i istediği için nginx de yükseltilir. Kurulum öncesi kontrolde sürüm yazılmamış kurulum komutu nginx'i 1.28.0'dan 1.30.6'ya yükseltme planı gösterdi.

Bu yüzden önce şu anda kurulu nginx sürümünü kontrol edin.

rpm -q nginx

nginx-1.28.0-1.el9.ngx.x86_64

Depoda her nginx sürümü için ayrı bir eş njs paketi vardır; sürüm numarasında + işaretinden önceki kısım nginx sürümü, sonraki kısım njs sürümüdür.

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

nginx 1.28.0 ile eşleşen sürümler 0.8.10'dan 0.9.4'e kadar altı tanedir; en üstteki @nginx-stable satırı kurulumu tamamlanmış sürümdür. Kurulumu bunların en yenisi olan 0.9.4 ile, sürüm numarasını tam yazarak yapın.

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

Kurulan paketin istediği nginx sürümünü rpm ile kontrol edebilirsiniz.

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

Kurulan dosyalar HTTP modülü, TCP/UDP işleyen stream modülü, her birinin hata ayıklama sürümü ve komut satırı aracı njs'dir. Bu ayarda yüklenen dosya yalnızca HTTP modülü [ngx_http_js_module.so].

4️⃣ js_set ayarı: Modülü yüklemekten önbellek dosyası yoluna

Paketi kurmak nginx'in modülü kendiliğinden yüklemesini sağlamaz; nginx.conf'un en üstünde [load_module] satırı olmalıdır. Resmî belgelere göre [load_module] main bağlamı yönergesidir, bu yüzden events ve http bloklarının dışına konur.

📂 /etc/nginx/Ayar klasörü

nginx.confEn üstte load_module — modülü yükler

njs/rocket.jslc işlevi — yalnızca yüzde kodlamasını küçük harfe

conf.d/

rocket-njs.confhttp bloğu — js_import · js_set

example.com.confserver bloğu — önbellek dosyası yolunda $rocket_uri

# /etc/nginx/nginx.conf en üstü (events ve http bloklarının dışı)
load_module modules/ngx_http_js_module.so;

Dönüştürme işlevi ayar dosyalarından ayrı bir .js dosyasında durur; nginx ayarı son satırda export default ile dışa aktarılan işlevi içe aktarır.

// /etc/nginx/njs/rocket.js — yalnızca yüzde kodlaması %XX küçük harfe
function lc(r) {
    return r.variables.request_uri.replace(/%[0-9A-F]{2}/g, function (m) { return m.toLowerCase(); });
}
export default { lc };

İşlev, istek nesnesi r'den [request_uri] değişkenini okur, yüzde işaretinden sonraki iki karakter büyük harfse yalnızca onları küçük harfe çevirip döndürür. Latin harfleri olduğu gibi kaldığından büyük harf içeren İngilizce adresler değişmez; bu, WP Rocket'ın önbellek klasörlerini adlandırma kuralıyla aynıdır.

# http bloğu içi (conf.d içindeki bir .conf dosyası)
js_import rkt from /etc/nginx/njs/rocket.js;
js_set $rocket_uri rkt.lc;

[js_import] içindeki rkt, modüldeki işlevleri çağırmak için kullanılan addır; [js_set] o işlevin sonucunu [$rocket_uri] değişkenine dönüştürür. Resmî belgelere göre bu işlev, değişkene istekte ilk kez başvurulduğunda çalışır ve yalnızca eşzamanlı işlemeyi destekler.

# server bloğu — önbellek dosyası yolundaki $request_uri yerine $rocket_uri
set $rocket_file '/wp-content/cache/wp-rocket/example.com${rocket_uri}index$rocket_mobile-https.html';

Değişen tek yer önbellek dosyası yolunu oluşturan bu satırdır; oturum açma çerezlerini, sorguları ve POST isteklerini önbellekten çıkaran kontroller olduğu gibi kalır.

5️⃣ Uygulama ve kontrol: reload sonrası hata kaydı ve yanıt başlıkları

Önce ayar testini çalıştırın, geçerse reload edin.

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

Yeni eklenen [load_module] satırı yeniden başlatmadan reload ile etkinleşti. Hata kaydında njs sanal makinesinin başlatıldığını gösteren bir satır kaldı, JavaScript hatası yoktu.

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

Satır sonundaki njs, kullanılan motorun adıdır. Aynı satır [nginx -t] ile ayar testi yapılırken de yazıldığından reload zamanıyla karşılaştırarak kontrol edin.

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

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

Büyük harfle kodlanmış Korece adreste de nginx'in önbellek dosyasıyla yanıt verdiğini gösteren başlık vardı. Sorgu ya da oturum açma çerezi olan istekler ve POST istekleri değişiklikten sonra da bu başlık olmadan PHP'ye geçti.

6️⃣ njs'i geri alma ve nginx güncelleme

Geri almak için önbellek dosyası yolundaki [$rocket_uri] değerini yeniden [$request_uri] yapın, [js_import]/[js_set] ayar dosyasını ve [load_module] satırını kaldırın, sonra ayar testinden geçirip reload edin.

# server bloğu — özgün değişkene
set $rocket_file '/wp-content/cache/wp-rocket/example.com${request_uri}index$rocket_mobile-https.html';

Paketi bırakabilirsiniz; [load_module] satırı yoksa nginx onu yüklemez, bu yüzden paketi yalnızca tamamen silmek istediğinizde kaldırın.

dnf remove nginx-module-njs

nginx'i güncellerken njs paketinin de yeni nginx sürümüyle eşleşen sürüme birlikte yükselmesi gerekir. Güncellemeden önce [dnf list --showduplicates] ile yeni nginx sürümünün njs eşinin depoda olup olmadığını kontrol edin.

🔢 SSS & önerilen içerikler

Resmî nginx belgeleri varsayılan njs motorunu 1.0.0 sürümünden itibaren kullanımdan kalkacak (deprecated) olarak işaretler ve yeni kurulumlar için ES2023'ü destekleyen QuickJS motorunu önerir. Motor, 0.8.6 sürümünden beri bulunan [js_engine qjs] yönergesiyle seçilir. Bu yazıdaki 0.9.4 kurulumu varsayılan njs motoruyla uygulandı, QuickJS'e geçiş denenmedi.

nginx olmadan njs kodu geliştirmek ve hata ayıklamak için kullanılan bağımsız bir komut satırı aracıdır (resmî belgelere göre). nginx-module-njs paketiyle birlikte kurulur; [njs -v] ile sürüme bakınca modülle aynı 0.9.4 görünür.

Yalnızca HTTP isteklerini işliyorsanız [ngx_http_js_module] yeterlidir. Pakette TCP/UDP oturumlarını işleyen [ngx_stream_js_module] de vardır; resmî kurulum belgeleri ikisinden gerekeni [load_module] ile yüklemenizi söyler.

🧭 WP Rocket ile ilgili yazılar 16 yazı · 3 araç

🗂️ WP nedir?

📋 WP Rocket ayar rehberi 📄 WP Rocket MCP Server 📄 WP Rocket ve Korece URL 📄 nginx njs 📄 WP Rocket çok dilli önbellek 📄 gclid önbelleği

📄 WP Rocket hız testi 📝 Önbellek·optimizasyon eklentileri 📝 Hızlandırma örneği

📋 Önbellek: tanımı ve tüm alanlar 📄 Web sitesi önbelleği & sunucu içi önbellek

📋 En iyi hosting TOP 7 📄 Hızlı hosting 2026

🛠️ WordPress tespiti 🛠️ Whois alan adı sorgulama 🛠️ IP adresim