Untuk menentukan versi Hugo tertentu pada platform Netlify, Anda harus mendefinisikan environment variable dengan nama HUGO_VERSION di dalam pengaturan situs atau melalui file konfigurasi netlify.toml. Langkah ini krusial untuk menghindari kegagalan build yang diakibatkan oleh ketidakcocokan antara versi Hugo lokal dengan versi default yang disediakan oleh server Netlify.
Secara default, Netlify menyediakan versi Hugo tertentu yang mungkin tertinggal dibandingkan rilis terbaru di GitHub. Dengan mengatur variabel lingkungan secara manual, Anda memiliki kendali penuh atas fitur, tema, dan fungsi shortcodes yang membutuhkan spesifikasi versi Hugo tertentu.
Metode Pengaturan HUGO_VERSION di Netlify
Terdapat dua cara utama untuk menetapkan versi Hugo di Netlify, yaitu melalui dasbor web Netlify (UI) atau menggunakan file netlify.toml di dalam repositori proyek Anda.
1. Mengatur melalui Netlify Dashboard (UI)
- Login ke akun Netlify Anda dan pilih situs web yang ingin dikonfigurasi.
- Navigasi ke menu Site configuration > Environment variables.
- Klik tombol Add a variable, lalu pilih Add a single variable.
- Masukkan
HUGO_VERSIONpada kolom Key. - Masukkan nomor versi Hugo yang diinginkan (contoh:
0.123.0) pada kolom Value. - Simpan perubahan dan lakukan Trigger deploy ulang pada situs Anda.
2. Mengatur melalui File netlify.toml
Cara ini sangat direkomendasikan karena konfigurasi versi Hugo akan tersimpan langsung di dalam kontrol versi (Git), sehingga setiap anggota tim atau server CI/CD menggunakan konfigurasi yang seragam.
[build.environment]
HUGO_VERSION = "0.123.0"
Tabel Perbandingan Metode Konfigurasi
| Metode | Lokasi Pengaturan | Kelebihan | Kekurangan |
|---|---|---|---|
| Netlify Dashboard | Web Admin Netlify | Cepat, tidak perlu mengubah kode repositori. | Tidak tercatat di Git, sulit dilacak jika tim bekerja dalam skala besar. |
| netlify.toml | Root direktori proyek | Terstandarisasi, otomatis ikut terdorong ke Git, mudah dibagikan. | Membutuhkan commit dan push ulang ke repository. |
Langkah Troubleshooting Jika Build Gagal
Jika proses build di Netlify masih mengalami kegagalan setelah menambahkan variabel lingkungan HUGO_VERSION, periksa beberapa hal berikut di lapangan:
- Format Versi Salah: Pastikan Anda tidak menyertakan huruf "v" di depan nomor versi. Gunakan format
0.111.3, bukanv0.111.3. - Cache Build Masih Aktif: Terkadang Netlify menggunakan cache lama saat proses build. Masuk ke menu Deploys > Trigger deploy, lalu centang opsi Clear cache and deploy site.
- Ext vs Standard: Pastikan tema atau modul Anda tidak membutuhkan varian Hugo Extended jika Anda telat memasang versi Standard (non-extended). Sebagian besar tema modern mewajibkan Hugo Extended.