Builder Toolkit · 07 / 11

Environment Variables

Fahami setting local berbanding hosted, nilai public berbanding server-only, dan kenapa variable baharu perlu rebuild.

Environment Variables

Apa ini

Environment variable ialah setting yang disimpan di luar code anda, supaya project yang sama boleh berkelakuan berbeza di tempat berbeza.

Project anda baca nama seperti SUPABASE_URL. Nilainya ada pada mesin anda dan dalam setting hosting anda, tidak pernah dalam code yang anda commit.

Satu idea utama

Code masuk Git. Nilai masuk environment. Pemisahan itulah yang membolehkan anda share code tanpa share key.

Kenapa penting

Ini punca nombor satu bagi "jalan di laptop saya tapi site live rosak".

File .env.local local anda sengaja diabaikan oleh Git. Ia tidak pernah sampai ke GitHub, jadi ia tidak pernah sampai ke host anda. Kalau anda tidak set nilai itu semula dalam dashboard hosting, build live tiada apa-apa untuk dibaca.

Apa nak buat

Fahami dua tempat

Tempat	File atau skrin	Digunakan oleh
Local	`.env.local` dalam root project	`npm run dev` pada mesin anda
Hosted	Setting environment variable host anda	Build live dan site live

Nama sama di kedua-dua tempat. Tempat letak berbeza. Set satu tidak set yang satu lagi.

Tulis file local

Copy

NEXT_PUBLIC_SUPABASE_URL=https://yourproject.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

Tiada tanda petik, tiada ruang sekeliling tanda sama dengan, satu per baris. Sahkan .env.local tersenarai dalam .gitignore sebelum anda commit apa-apa.

Tahu nilai mana yang public

Perbezaan ini melindungi anda, dan beginner selalu salah faham.

Jenis	Penamaan	Ia berakhir di mana	Selamat didedahkan
Public	Ada prefix, contoh `NEXT_PUBLIC_`	Dibungkus ke dalam code browser	Ya, memang begitu tujuannya
Server-only	Tiada prefix	Kekal pada server	Tidak, tidak sekali-kali

Nilai NEXT_PUBLIC_ boleh dilihat sesiapa yang buka developer tools pada site anda. Itu memang untuk benda seperti URL project public. Jangan sekali-kali beri prefix itu kepada service role key, password database, atau token peribadi.

Prefix itu keputusan, bukan formaliti

Tambah NEXT_PUBLIC_ pada secret untuk senyapkan error bermakna menerbitkan secret itu kepada setiap pelawat. Kalau nilai gagal sebab ia tidak sampai ke browser, fixnya biasanya pindahkan kerja itu ke server, bukan dedahkan key.

Tambah ke host anda

Buka setting project pada host dan cari environment variables.
Tambah setiap nama dan nilai tepat seperti dalam file local anda.
Save.
Redeploy. Deployment sedia ada tidak ambil nilai baharu.

Buat sekarang

Buka skrin environment variable hosting anda dan banding baris demi baris dengan .env.local local anda. Mana-mana nama yang ada di satu tempat sahaja ialah bug live yang sedang menunggu.

Check sendiri

.env.local wujud di local dan diabaikan oleh Git.
Setiap variable yang project saya perlukan juga di-set pada host.
Saya boleh terangkan variable mana public dan mana server-only.
Saya tahu variable baharu perlukan redeploy.

Kalau site live error tetapi local okay

Sembilan daripada sepuluh kali ia variable yang hilang atau salah eja pada host, atau variable ditambah tanpa redeploy. Semak dua itu sebelum sentuh mana-mana code.

Common mistakes

Anggap .env.local naik bersama project. Ia tidak pernah naik.
Tambah variable pada host dan tidak redeploy.
Salah taip nama. SUPBASE_URL gagal senyap dan nampak macam bug code.
Tandakan secret sebagai public untuk hilangkan error.
Simpan nilai berbeza di local dan pada host, kemudian debug perbezaan hantu.
Paste seluruh file .env ke dalam chat atau screenshot semasa minta bantuan.

Next step

Setting anda betul di kedua-dua tempat. Sekarang beri project alamat sebenar: Domain dan DNS.