Saya baru saja deploy beberapa perbaikan CSS ke staging sebuah situs klien: fix garis yang bergeser, pengerasan animasi fx-clip-up, dan penghapusan garis putus-putus yang tidak diminta. Buka staging, dan perilaku lamanya masih di sana. Semua animasi scroll tampil sebagai satu gerakan fade-up yang seragam, monoton, padahal di markup jelas-jelas ada campuran class fx-mask, fx-scale, dan fx-slide yang seharusnya bikin tiap seksi masuk dengan gaya berbeda. CSS baru saya seolah tidak pernah sampai.
Yang bikin saya makin bingung: file di disk sudah benar. Saya buka file CSS di server, isinya persis versi baru. Saya bahkan bandingkan MD5 dari CSS yang benar-benar dikirim ke browser dengan MD5 file di disk, dan cocok. Server mengirim byte yang benar. Tapi browser saya tetap menampilkan animasi lama.
Semua cache sudah saya buang
Refleks pertama saya di stack WordPress dengan LiteSpeed di depannya: purge cache. Saya klik purge all di LiteSpeed. Refresh, masih lama. Lalu saya ingat ada Cloudflare di depan LiteSpeed, jadi saya purge Cloudflare juga. Refresh, masih lama. Saya flush object cache Redis-nya. Masih. Setiap lapisan cache yang saya tahu sudah saya buang, dan animasi monoton itu tetap keras kepala di layar.
Di titik itu saya berhenti dan bikin daftar apa yang sudah saya eliminasi. Disk benar. Byte yang dikirim benar, MD5 cocok. LiteSpeed Page Cache sudah dibuang. Cloudflare sudah dibuang. Redis sudah dibuang. Kalau server benar-benar mengirim CSS baru dan saya tetap lihat yang lama, cuma ada satu tempat sisa yang bisa menyimpan versi basi: browser saya sendiri.
Akar masalahnya ada di query string
Di WordPress, aset di-enqueue lewat wp_enqueue_style dan wp_enqueue_script, dan argumen versinya berubah jadi query string di URL akhir:
wp_enqueue_style(
'theme-main',
get_stylesheet_directory_uri() . '/style.css',
array(),
THEME_VERSION
);Hasilnya di HTML kira-kira begini:
<link rel="stylesheet" href="/wp-content/themes/mytheme/style.css?ver=4.4.0" />Yang krusial: browser meng-cache aset berdasarkan URL lengkap, termasuk query string. Bagi browser, style.css?ver=4.4.0 adalah satu identitas yang utuh. Selama URL itu tidak berubah, browser merasa berhak melayani salinan yang sudah dia simpan tanpa repot menanyakan versi baru ke server. Dan THEME_VERSION di functions.php masih 4.4.0, persis seperti sebelum saya deploy. URL asetnya identik dengan kemarin.
Ini menjelaskan kenapa semua purge saya sia-sia. Rantai cache di staging itu punya empat lapis:
1. Cache browser -> dikunci oleh URL + ?ver=
2. Cloudflare CDN
3. LiteSpeed Page Cache
4. Redis object cache (LiteSpeed)Purge LiteSpeed membersihkan lapis 3 dan 4. Purge Cloudflare membersihkan lapis 2. Tapi tidak ada satu pun tombol purge di server yang bisa menyentuh lapis 1. Cache browser hidup di mesin pengunjung, dan satu-satunya cara memberitahunya bahwa ini file baru adalah dengan mengubah URL-nya.
Ada satu detail yang seharusnya jadi lampu merah lebih awal: bug ini cuma terjadi buat saya. Pengunjung baru yang belum pernah buka staging akan mengunduh ?ver=4.4.0 untuk pertama kali dan langsung dapat CSS baru, mulus. Yang tersiksa cuma saya, orang yang berulang kali refresh sepanjang sesi deploy dan sudah menyimpan versi lama di cache lokal. Pola "cuma rusak di tempat saya, pengunjung lain fine" itu tanda klasik masalah cache browser, bukan bug kode.
Perbaikannya cuma satu baris
Perbaikannya tidak menyentuh CSS sama sekali, karena CSS-nya memang sudah benar. Saya cukup menaikkan konstanta versinya di functions.php:
// Sebelum
define( 'THEME_VERSION', '4.4.0' );
// Sesudah
define( 'THEME_VERSION', '4.4.1' );Begitu di-deploy, setiap tag link dan script otomatis berubah jadi ?ver=4.4.1. Bagi browser itu URL baru yang belum pernah dia lihat, jadi dia terpaksa mengambilnya segar dari server. Animasi yang tadinya monoton langsung tampil dengan variasi fx-mask, fx-scale, dan fx-slide yang benar. Nol perubahan kode lain. Selama iterasi hari itu saya naikkan lagi ke 4.4.2 untuk ship berikutnya, dan seterusnya.
Setelah itu saya adopsi aturan sederhana: bump THEME_VERSION untuk setiap kali ship CSS atau JS, sekecil apa pun perubahannya. Satu baris murah. Alternatifnya adalah berjam-jam bingung membedakan cache basi atau perbaikan saya yang salah, yang persis jebakan yang baru saja saya masuki.
Checklist
- Kalau CSS atau JS baru tidak muncul padahal semua cache server sudah di-purge, curigai cache browser yang dikunci oleh
?ver=. - Eliminasi dulu: cek file di disk, bandingkan MD5 yang dikirim server dengan file di disk. Kalau server mengirim byte yang benar tapi kamu tetap lihat yang lama, tersangkanya browser.
- Ingat urutan lapisannya: browser -> Cloudflare -> LiteSpeed Page Cache -> Redis. Tombol purge di server cuma menyentuh lapisan 2 sampai 4.
- Gejala "cuma basi di browser saya, pengunjung baru fine" adalah tanda kuat cache browser, bukan bug kode.
- Bump konstanta versi (
THEME_VERSION) difunctions.phpsetiap ship aset, walau trivial.wp_enqueue_styleakan menaruhnya sebagai?ver=Xdan memaksa fetch segar. - Jangan pernah andalkan pengunjung untuk hard-refresh. Ubah URL asetnya, dan cache browser mengurus dirinya sendiri.