Vercel: Pemboleh Ubah Persekitaran Tanpa .env dalam Git

Panduan ini adalah untuk projek yang sudah dihoskan pada Vercel. Anda memerlukan akses kepada tetapan projek dan perlu mengetahui pemboleh ubah yang dibaca oleh aplikasi. Contoh di bawah digunakan untuk Next.js; nama pemboleh ubah daripada rangka kerja lain tidak boleh digunakan secara automatik. Panduan ini berdasarkan dokumentasi rasmi; panduan ini belum diuji pada akaun sebenar.

Maklumat praktikal tentang penggunaan Ailoot tersedia dalam dokumentasi.

Mengapa anda tidak perlu menambahkan .env pada Git#

Pemboleh ubah persekitaran ialah tetapan yang mempunyai nama dan nilai, yang diterima oleh aplikasi secara berasingan daripada kod sumbernya. Contohnya, nama SERVICE_API_KEY membolehkan program mengakses nilai kunci perkhidmatan luaran. Jangan letakkan kunci itu sendiri dalam panduan, perbualan anda dengan ejen atau repositori.

Next.js boleh memuatkan pemboleh ubah daripada fail .env* setempat. Walau bagaimanapun, fail setempat dan tetapan projek dalam Vercel ialah dua lokasi yang berasingan. Jika fail itu tidak dihantar ke repositori, tetapkan nilainya secara berasingan pada platform pengehosan. Templat standard create-next-app menambahkan fail .env pada .gitignore; dokumentasi Next.js memberi amaran bahawa anda hampir tidak patut menghantarnya ke repositori.

Jika anda masih tidak pasti perkara yang boleh disimpan dalam fail sumber, mulakan dengan semakan keselamatan untuk projek yang dibina dengan AI. Di sini, kita membincangkan soalan yang lebih khusus: tempat menetapkan konfigurasi untuk deployment Vercel tertentu.

Mula-mula, tentukan tempat aplikasi membaca pemboleh ubah#

Sebelum memasukkan sebarang nilai, senaraikan nama pemboleh ubah tanpa menyertakan rahsia itu sendiri. Bagi setiap nama, anda perlu menentukan tiga perkara: persekitaran yang menggunakannya, tempat kod yang membaca pemboleh ubah itu berjalan dan masa nilai itu diperlukan.

Persekitaran Development ditujukan untuk pembangunan setempat. Preview digunakan untuk deployment pratonton, manakala Production digunakan untuk versi utama yang diterbitkan. Preview boleh mempunyai tetapan khusus untuk cawangan Git: tetapan ini mengatasi tetapan Preview umum yang mempunyai nama yang sama.

Dalam projek Next.js, pemboleh ubah tanpa NEXT_PUBLIC_ tersedia pada pelayan secara lalai. Awalan NEXT_PUBLIC_ membolehkan nilai dimasukkan dalam JavaScript yang dihantar ke pelayar. Awalan ini sesuai untuk tetapan yang memang bersifat awam, seperti label versi yang bukan rahsia, tetapi bukan untuk kunci API peribadi. Walaupun tanpa awalan ini, kod aplikasi tidak boleh memulangkan rahsia secara manual kepada klien.

Jika anda belum mengenal pasti rangka kerja yang digunakan, minta ejen mengenal pastinya daripada fail projek. Perbandingan Astro dengan Next.js boleh membantu anda memahami perbezaannya; peraturan NEXT_PUBLIC_ tidak boleh digunakan untuk setiap aplikasi React.

Konfigurasi pengehosan ialah salah satu tugas dalam bekerja dengan aplikasi menggunakan ejen AI.

Cara menambahkan pemboleh ubah pada projek Vercel#

Lakukan sendiri langkah-langkah dalam papan pemuka rasmi. Jangan berikan kunci sebenar kepada ejen untuk mengisi borang dan jangan lampirkan tangkap layar yang menunjukkan nilainya.

1. Buka papan pemuka Vercel dan pilih projek yang betul. Jangan bergantung semata-mata pada nama repositori yang sepadan: pastikan anda mengkonfigurasi aplikasi yang ingin dibuka.
2. Pergi ke Environment Variables dalam bar sisi tetapan projek.
3. Dalam Name, masukkan nama yang dibaca oleh aplikasi, seperti SERVICE_API_KEY. Ini ialah nama contoh; jika kod menjangkakan nama lain, gunakan ejaan yang tepat.
4. Dalam Value, masukkan nilai daripada stor kelayakan anda. Jangan masukkannya dalam kod sumber, perbualan atau log pengesahan.
5. Pilih persekitaran yang memerlukan tetapan ini. Gunakan Preview untuk menyemak versi pratonton dan Production untuk versi utama. Jangan tetapkan satu rahsia kepada semua persekitaran secara automatik.
6. Jika tetapan Preview digunakan untuk cawangan tertentu, semak cawangan yang dipilih dan sebarang tetapan yang mengatasi nilai umum dengan nama yang sama.
7. Klik Save.

Vercel menyediakan pemboleh ubah projek semasa binaan dan apabila Vercel Functions sisi pelayan dijalankan. Walau bagaimanapun, nilai yang tersedia dalam Vercel tidak bermakna nilai itu boleh dihantar kepada pelayar: perkara ini bergantung pada kod aplikasi dan peraturan rangka kerja.

Mengapa anda memerlukan deployment baharu selepas menekan Save#

Menyimpan pemboleh ubah tidak mengubah deployment sedia ada. Dokumentasi Vercel menghendaki anda membuat deployment semula agar tetapan baharu digunakan pada versi yang anda gunakan.

Apabila bekerja melalui Git, anda boleh membuat deployment Production baharu dengan menghantar commit ke cawangan yang dinyatakan dalam Production Branch, dan deployment Preview dengan menghantar commit ke cawangan lain. Jangan anggap cawangan utama sentiasa bernama main: semak tetapan projek anda. Ini sepatutnya merupakan keluaran projek biasa yang dipersetujui, tanpa menambahkan fail rahsia pada commit.

Selepas memulakan deployment, tunggu sehingga binaan selesai dan buka URL deployment baharu. Catat URL, persekitaran dan cawangannya. Jika anda menyemak URL lama bagi deployment tertentu, tetapan baharu tidak akan muncul di situ.

Next.js mempunyai satu lagi syarat: rujukan seperti process.env.NEXT_PUBLIC_RELEASE_LABEL digantikan dengan nilainya semasa next build. Nilai itu kekal selepas binaan. Mengubah tetapan tanpa binaan baharu tidak akan mengubah JavaScript sisi klien yang sudah dihantar.

Cara menyemak hasil tanpa mendedahkan kunci#

Mulakan dengan contoh yang selamat: label yang jelas bukan rahsia bernama NEXT_PUBLIC_RELEASE_LABEL dengan nilai preview-check. Ini ialah nama dan teks contoh, bukannya kunci atau ujian yang dilakukan di sini. Jika aplikasi Next.js membaca pemboleh ubah ini secara langsung melalui process.env.NEXT_PUBLIC_RELEASE_LABEL, aplikasi itu boleh memaparkan label tersebut di tempat yang dimaksudkan dalam antara muka selepas binaan baharu. Semakan ini hanya mengesahkan bahawa tetapan awam itu telah diteruskan.

Kunci peribadi disemak dengan cara yang berbeza. Jangan paparkan nilainya, sebahagian daripadanya, panjangnya atau keseluruhan process.env. Jangan cipta URL awam yang memulangkan kandungan pemboleh ubah itu. Mula-mula, semak hanya sama ada tetapan itu “ada / tiada” pada pelayan, kemudian semak secara berasingan fungsi aplikasi yang menggunakan perkhidmatan tersebut. Kehadiran tetapan tidak membuktikan bahawa kunci itu sah atau mempunyai kebenaran yang diperlukan.

Anda boleh merekodkan hasil tanpa rahsia:

• projek, persekitaran dan cawangan sepadan dengan pilihan semasa konfigurasi;
• anda sedang menyemak URL deployment baharu yang dibuat selepas pemboleh ubah disimpan;
• binaan telah selesai dan fungsi aplikasi yang diperlukan telah dijalankan dengan data ujian yang selamat;
• rahsia tidak didedahkan dalam pelayar, respons API, log atau perbualan.

Jika fungsi itu membuat pembayaran, menghantar mesej atau melakukan tindakan lain yang mempunyai kesan, gunakan mod ujian yang ditetapkan oleh perkhidmatan. Menyemak konfigurasi sahaja tidak memberikan kebenaran untuk melakukan operasi sebenar.

Perkara yang perlu disemak jika nilai masih undefined#

undefined bermaksud tiada nilai diperoleh pada titik akses tersebut. Semak nama, persekitaran dan versi mengikut turutan, tanpa mengubah semua tetapan serentak.

Selepas anda menyemak nama, persekitaran dan versi baharu, ralat dalam fungsi itu masih tidak membuktikan bahawa pemboleh ubah menjadi puncanya. Siasat ralat kod sisi pelayan yang khusus tanpa menerbitkan data diagnostik yang mengandungi rahsia. Panduan ini tidak menjanjikan penyelesaian bagi setiap respons HTTP 500.

Beralih kepada pelayan sendiri memerlukan prosedur yang berbeza: lihat panduan untuk men-deploy projek dengan Coolify. Nama butang dan langkah konfigurasi Vercel tidak terpakai padanya.

Pergi ke Ailoot.