# Vercel: Pemboleh Ubah Persekitaran Tanpa .env dalam Git

> Pemboleh ubah persekitaran, Development/Preview/Production, deployment baharu dan cara menyemak kunci dengan selamat dalam Next.js tanpa menghantar rahsia kepada pelayar.

Source: https://ailoot.ai/blog/ms/vercel-environment-variables/
Canonical: https://ailoot.ai/blog/ms/vercel-environment-variables/
Language: ms
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-229
Revision: sha256-0d504c1f4064d3dc46a4e6cbcbfa68ec9da52e83714e9fa2643734346571ff72


<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Perkara utama untuk bahagian ini">

Perkara utama

Jika fail `.env` yang mengandungi rahsia anda tiada dalam Git, tambahkan pemboleh ubah yang diperlukan dalam bahagian **Environment Variables** projek Vercel anda. Pilih persekitaran, simpan tetapan dan buat deployment baharu: versi yang sudah dideploy tidak akan berubah. Dalam Next.js, jangan tambahkan awalan `NEXT_PUBLIC_` pada kunci rahsia: nilainya akan dimasukkan ke dalam kod pelayar semasa binaan.

</div>

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](https://ailoot.ai/docs/).

## 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](https://ailoot.ai/blog/ms/vibe-coding-security/). 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.

| Perkara yang perlu disemak | Pilihan yang mungkin | Sebab perkara ini penting |
|----|----|----|
| Persekitaran Vercel | Development, Preview, Production | Tetapan itu mesti digunakan pada versi yang sedang anda semak |
| Tempat pemboleh ubah dibaca | Pelayan atau pelayar | Kunci peribadi tidak boleh dimasukkan dalam kod sisi klien |
| Masa pemboleh ubah dibaca | Semasa binaan atau pelaksanaan fungsi pelayan | Dalam Next.js, nilai awam ditetapkan semasa binaan |

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](https://ailoot.ai/blog/ms/astro-vs-nextjs-for-ai-built-sites/) 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.

| Gejala | Perkara yang perlu disemak |
|----|----|
| Berfungsi setempat, tetapi tidak dalam Preview | Sama ada nama itu wujud dalam tetapan Preview projek; sama ada cawangan lain dipilih |
| Preview berfungsi, tetapi Production tidak | Sama ada nama itu ditetapkan untuk Production; sama ada versi utama baharu dibuat selepas menekan Save |
| Satu cawangan Preview berkelakuan berbeza | Sama ada nilai dengan nama yang sama ditetapkan untuk cawangan itu dan mengatasi tetapan umum |
| Pelayan melihat pemboleh ubah, tetapi pelayar tidak | Dalam Next.js, ini dijangka bagi pemboleh ubah bukan awam; jangan pindahkan kunci peribadi ke pelayar |
| Label awam Next.js masih mempunyai nilai lama | Sama ada binaan baharu dibuat dengan nilai yang diperlukan; sama ada URL yang dibuka milik deployment itu |
| Nama awam betul, tetapi penggantian tidak berfungsi | Sama ada kod membacanya secara dinamik dengan `process.env[varName]`: Next.js tidak memasukkan rujukan ini dalam kod |

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](https://ailoot.ai/blog/ms/coolify-claude-code-deploy/). Nama butang dan langkah konfigurasi Vercel tidak terpakai padanya.

<div class="section" role="doc-bibliography" aria-label="Sumber">

### Sumber

- [Pemboleh ubah persekitaran Vercel](https://vercel.com/docs/environment-variables)
- [Menambah dan mengurus pemboleh ubah persekitaran Vercel](https://vercel.com/docs/environment-variables/managing-environment-variables)
- [Pemboleh ubah persekitaran Next.js](https://nextjs.org/docs/app/guides/environment-variables)

</div>





[Pergi ke Ailoot](https://ailoot.ai/).

## Soalan lazim: Vercel: Pemboleh Ubah Persekitaran Tanpa .env dalam Git

### Mengapakah pemboleh ubah masih undefined selepas disimpan dalam Vercel?

Semak projek, persekitaran dan sebarang skop khusus cabang, kemudian cipta penggunaan baharu. Penggunaan sedia ada tidak mendapat pemboleh ubah hanya kerana tetapan baharu disimpan.

### Bolehkah saya menambah NEXT_PUBLIC_ untuk menjadikan rahsia kelihatan kepada aplikasi Next.js?

Jangan gunakan awalan itu untuk rahsia: ia memasukkan nilai ke kod pelayar semasa binaan. Kekalkan pada pelayan dan sahkan kewujudan tanpa mencetak kunci.


## Ailoot · Syarikat dan portfolio projeknya

Ailoot berteraskan pengalaman operasi yang mantap, pangkalan pelanggan yang besar, perkhidmatan yang stabil dan pemantauan KPI berterusan.

Syarikat dan portfolio projeknya: jutaan pelanggan; jualan bernilai berbilion setiap bulan.

Ailoot menggunakan pengalaman operasi ini untuk akses API kepada ciri AI dalam produk pelanggan, ejen, aplikasi dan automasi.