Vercel: Variabel Lingkungan Tanpa .env di Git

Panduan ini ditujukan untuk proyek yang sudah dihosting di Vercel. Anda memerlukan akses ke pengaturannya dan pemahaman tentang variabel yang dibaca aplikasi. Contoh di bawah berlaku untuk Next.js; nama variabel dari framework lain tidak dapat diterapkan secara otomatis. Panduan ini didasarkan pada dokumentasi resmi; panduan ini belum diuji pada akun sungguhan.

Informasi praktis tentang penggunaan Ailoot tersedia di dokumentasi.

Mengapa Anda tidak perlu menambahkan .env ke Git#

Variabel lingkungan adalah pengaturan yang memiliki nama dan nilai, yang diterima aplikasi secara terpisah dari kode sumbernya. Contohnya, nama SERVICE_API_KEY memungkinkan program mengakses nilai kunci layanan eksternal. Jangan cantumkan kunci itu sendiri dalam panduan, percakapan dengan agen, atau repositori.

Next.js dapat memuat variabel dari file .env* lokal. Namun, file lokal dan pengaturan proyek di Vercel berada di dua lokasi terpisah. Jika file tersebut tidak di-push ke repositori, atur nilainya secara terpisah di platform hosting. Templat standar create-next-app menambahkan file .env ke .gitignore; dokumentasi Next.js memperingatkan bahwa Anda hampir tidak boleh mengirim file tersebut ke repositori.

Jika Anda masih ragu tentang apa yang boleh disimpan dalam file sumber, mulailah dengan pemeriksaan keamanan untuk proyek yang dibuat dengan AI. Di sini, kita membahas pertanyaan yang lebih spesifik: di mana mengatur konfigurasi untuk deployment Vercel tertentu.

Pertama, tentukan tempat aplikasi membaca variabel#

Sebelum memasukkan nilai apa pun, buat daftar nama, tanpa rahasianya. Untuk setiap nama, Anda perlu memastikan tiga hal: lingkungan mana yang menggunakannya, di mana kode yang membaca variabel berjalan, dan kapan nilai tersebut diperlukan.

Lingkungan Development ditujukan untuk pengembangan lokal. Preview digunakan untuk deployment pratinjau, sedangkan Production untuk versi utama yang dipublikasikan. Preview dapat memiliki pengaturan untuk cabang Git tertentu: pengaturan tersebut menggantikan pengaturan Preview umum dengan nama yang sama.

Dalam proyek Next.js, variabel tanpa NEXT_PUBLIC_ secara default tersedia di server. Prefiks NEXT_PUBLIC_ memungkinkan nilai disematkan ke JavaScript yang dikirim ke browser. Ini cocok untuk pengaturan yang memang bersifat publik, seperti label versi yang bukan rahasia, tetapi tidak untuk kunci API privat. Meskipun prefiks ini tidak digunakan, kode aplikasi tetap tidak boleh mengirim rahasia secara manual ke klien.

Jika Anda belum mengidentifikasi framework yang digunakan, minta agen mengidentifikasinya dari file proyek. Perbandingan Astro dan Next.js dapat membantu Anda memahami perbedaannya; aturan NEXT_PUBLIC_ tidak dapat diterapkan ke setiap aplikasi React.

Konfigurasi hosting adalah salah satu tugas dalam mengerjakan aplikasi dengan agen AI.

Cara menambahkan variabel ke proyek Vercel#

Lakukan sendiri langkah-langkah ini di dasbor resmi. Jangan memberikan kunci sungguhan kepada agen untuk mengisi formulir, dan jangan melampirkan tangkapan layar yang menampilkan nilainya.

1. Buka dasbor Vercel dan pilih proyek yang benar. Jangan hanya mengandalkan nama repositori yang cocok: pastikan Anda mengonfigurasi aplikasi yang memang ingin dibuka.
2. Buka Environment Variables di bilah sisi pengaturan proyek.
3. Di kolom Name, masukkan nama yang dibaca aplikasi, misalnya SERVICE_API_KEY. Ini hanya nama contoh; jika kode mengharapkan nama lain, gunakan ejaan yang persis sama.
4. Di kolom Value, masukkan nilai dari penyimpanan kredensial Anda. Jangan masukkan nilai itu ke kode sumber, obrolan, atau log verifikasi.
5. Pilih lingkungan yang memerlukan pengaturan ini. Gunakan Preview untuk memeriksa versi pratinjau dan Production untuk versi utama. Jangan otomatis menetapkan satu rahasia ke semua lingkungan.
6. Jika pengaturan Preview berlaku untuk cabang tertentu, periksa cabang yang dipilih serta pengaturan pengganti dengan nama yang sama.
7. Klik Save.

Vercel menyediakan variabel proyek selama proses build dan saat Vercel Functions sisi server berjalan. Namun, tersedianya nilai di Vercel tidak berarti nilai itu boleh dikirim ke browser: hal tersebut bergantung pada kode aplikasi dan aturan framework.

Mengapa Anda memerlukan deployment baru setelah Save#

Menyimpan variabel tidak mengubah deployment yang sudah ada. Dokumentasi Vercel mengharuskan Anda melakukan deployment ulang agar pengaturan baru diterapkan pada versi yang Anda gunakan.

Jika bekerja melalui Git, Anda dapat membuat deployment Production baru dengan mengirim commit ke cabang yang ditentukan dalam Production Branch, dan deployment Preview dengan mengirim commit ke cabang lain. Jangan berasumsi bahwa cabang utama selalu bernama main: periksa pengaturan proyek Anda. Ini sebaiknya menjadi rilis proyek yang normal dan telah disepakati, tanpa menambahkan file rahasia ke commit.

Setelah memulai deployment, tunggu hingga build selesai, lalu buka URL deployment baru. Catat URL, lingkungan, dan cabangnya. Jika Anda memeriksa URL deployment lama, pengaturan baru tidak akan muncul di sana.

Next.js memiliki ketentuan lain: referensi seperti process.env.NEXT_PUBLIC_RELEASE_LABEL diganti dengan nilainya selama next build. Nilai tersebut ditetapkan setelah build. Mengubah pengaturan tanpa melakukan build baru tidak akan memperbarui JavaScript sisi klien yang sudah dikirim.

Cara memeriksa hasil tanpa mengungkapkan kunci#

Mulailah dengan contoh yang aman: label yang secara eksplisit bukan rahasia, bernama NEXT_PUBLIC_RELEASE_LABEL dengan nilai preview-check. Nama dan teks tersebut hanya contoh, bukan kunci atau pengujian yang dilakukan di sini. Jika aplikasi Next.js membaca variabel ini langsung melalui process.env.NEXT_PUBLIC_RELEASE_LABEL, aplikasi dapat menampilkan label tersebut di tempat yang dimaksud pada antarmuka setelah build baru. Pemeriksaan ini hanya mengonfirmasi bahwa pengaturan publik telah diteruskan.

Kunci privat diperiksa dengan cara berbeda. Jangan tampilkan nilainya, sebagian nilainya, panjangnya, atau seluruh process.env. Jangan membuat URL publik yang mengembalikan isi variabel tersebut. Pertama, periksa hanya apakah pengaturan itu “ada / tidak ada” di server, lalu periksa secara terpisah fungsi aplikasi yang menggunakan layanan tersebut. Adanya pengaturan tidak membuktikan bahwa kunci itu valid atau memiliki izin yang diperlukan.

Anda dapat mencatat hasilnya tanpa rahasia:

• proyek, lingkungan, dan cabangnya sama dengan yang dipilih saat konfigurasi;
• Anda memeriksa URL deployment baru yang dibuat setelah variabel disimpan;
• build telah selesai, dan fungsi aplikasi yang diperlukan telah dijalankan menggunakan data pengujian yang aman;
• rahasia tidak terungkap di browser, respons API, log, atau percakapan.

Jika fungsi tersebut melakukan pembayaran, mengirim pesan, atau menjalankan tindakan lain yang berdampak, gunakan mode pengujian yang disediakan layanan. Memeriksa konfigurasi saja tidak memberikan izin untuk menjalankan operasi sungguhan.

Yang perlu diperiksa jika nilainya masih undefined#

undefined berarti tidak ada nilai yang diperoleh pada titik akses tersebut. Periksa nama, lingkungan, dan versi secara berurutan, tanpa mengubah semua pengaturan sekaligus.

Setelah memeriksa nama, lingkungan, dan versi baru, kesalahan pada fungsi tetap tidak membuktikan bahwa penyebabnya adalah variabel. Selidiki kesalahan spesifik pada kode sisi server tanpa memublikasikan data diagnostik yang berisi rahasia. Panduan ini tidak menjanjikan penyelesaian untuk setiap respons HTTP 500.

Beralih ke server milik Anda sendiri memerlukan prosedur berbeda: lihat panduan deployment proyek dengan Coolify. Nama tombol dan langkah konfigurasi Vercel tidak berlaku untuk Coolify.

Kunjungi Ailoot.