💡 ULASAN & REFERENSI • DIPERBARUI: 20 October 2026 • REDAKSI AZWINN

Nginx SSI Module: Panduan Konfigurasi dan Direktif

Modul ngx_http_ssi_module adalah komponen bawaan Nginx yang bertugas memproses Server Side Includes (SSI)—yakni instruksi atau direktif yang disisipkan ke dalam file HTML untuk menggabungkan dokumen secara dinamis sebelum dikirimkan ke peramban klien. Modul ini memungkinkan penggunaan kembali komponen situs yang statis secara efisien, seperti header, footer, atau sidebar, tanpa memerlukan pemrosesan skrip backend yang berat seperti PHP untuk setiap pemanggilan bagian yang berulang.

Secara default, modul SSI tidak diaktifkan pada proses kompilasi jika menggunakan beberapa paket minimalis tertentu, namun pada instalasi standar Nginx melalui repositori resmi (APT, Yum) atau Docker image resmi, modul ini sudah tersedia dan siap dikonfigurasi melalui blok server atau blok location pada file nginx.conf.

Direktif Utama Nginx SSI

Untuk mengimplementasikan SSI pada server Nginx, terdapat beberapa direktif esensial yang harus dipahami guna mengatur perilaku pemrosesan dokumen oleh server:

Nama Direktif Sintaks Default Fungsi Utama
ssi ssi on | off; Mengaktifkan atau menonaktifkan pemrosesan SSI pada konteks yang ditentukan (http, server, location).
ssi_silent_errors ssi_silent_errors on | off; Menyembunyikan pesan kesalahan seperti '[an error occurred while processing the directive]' ketika terjadi kegagalan inklusi.
ssi_types ssi_types text/html ...; Menentukan tipe MIME apa saja yang akan diproses oleh modul SSI selain tipe default text/html.
ssi_value_length ssi_value_length 256; Menetapkan batasan panjang maksimum untuk nilai variabel di dalam SSI.

Contoh Konfigurasi Nginx SSI

Penerapan konfigurasi SSI dilakukan di dalam berkas konfigurasi Nginx. Di bawah ini adalah contoh blok location yang mengaktifkan SSI serta mengizinkan pemrosesan pada tipe file tambahan seperti text/plain.

server {
    listen 80;
    server_name contoh.lokal;

    root /var/www/html;
    index index.html index.htm;

    location / {
        ssi on;
        ssi_silent_errors off;
        ssi_types text/html text/plain;
        try_files $uri $uri/ =404;
    }
}

Sintaks SSI yang Didukung

Setelah modul diaktifkan di sisi Nginx, berkas HTML Anda dapat disisipi sintaks khusus berbasis komentar HTML. Nginx akan membaca pola ini, mengeksekusinya, lalu menggantinya dengan hasil keluaran dari berkas atau variabel yang dipanggil.

Berikut adalah format penulisan dasar direktif SSI di dalam file HTML:

<!--#include virtual="/includes/header.html" -->
<!--#include file="footer.html" -->
<!--#echo var="date_local" -->
  • virtual: Mengambil sumber daya berdasarkan jalur relatif terhadap server atau URL path.
  • file: Mengambil sumber daya berdasarkan jalur relatif terhadap direktori file HTML yang sedang diproses.
  • echo: Menampilkan variabel internal Nginx atau variabel yang didefinisikan sebelumnya.

Troubleshooting dan Tips Lapangan

Ketika menerapkan Nginx SSI, beberapa kendala umum sering ditemui oleh administrator sistem. Berikut adalah cara mengatasinya:

  • Halaman Kosong atau Error SSI: Jika muncul teks error di halaman web, pastikan jalur file pada atribut virtual atau file benar dan dapat diakses oleh proses Nginx (periksa izin akses atau permission Linux).
  • Header Respons Terpotong (Content-Length): Karena Nginx mengubah ukuran konten secara dinamis saat melakukan inklusi file, modul SSI secara otomatis menangani transfer encoding menjadi chunked untuk mencegah masalah panjang konten yang tidak sinkron.
  • Kompatibilitas dengan Caching: Penggunaan SSI dapat mengurangi efektivitas caching halaman penuh (full-page cache) konvensional karena setiap permintaan memerlukan evaluasi server. Gunakan mekanisme caching tingkat fragmen (fastcgi_cache atau proxy_cache dengan subrequests) bila diperlukan performa tinggi.

🔍 Orang Lain Juga Mencari Ini