Vercel: spremenljivke okolja brez datoteke .env v Gitu

Ta vodnik je namenjen projektu, ki že gostuje na Vercelu. Potrebujete dostop do njegovih nastavitev in morate vedeti, katere spremenljivke aplikacija bere. Spodnji primer velja za Next.js; imen spremenljivk iz drugega ogrodja ni mogoče samodejno prenesti. Vodnik temelji na uradni dokumentaciji; na pravem računu ni bil preizkušen.

Praktične informacije o uporabi Ailoota so na voljo v dokumentaciji.

Zakaj datoteke .env ni treba dodati v Git#

Spremenljivka okolja je nastavitev z imenom in vrednostjo, ki jo aplikacija prejme ločeno od izvorne kode. Ime SERVICE_API_KEY na primer programu omogoča dostop do vrednosti ključa zunanje storitve. Samega ključa ne vključite v vodnik, pogovor z agentom ali repozitorij.

Next.js lahko naloži spremenljivke iz lokalnih datotek .env*. Vendar sta lokalna datoteka in nastavitev projekta v Vercelu dve ločeni mesti. Če datoteke ne pošljete v repozitorij, vrednosti nastavite ločeno na platformi za gostovanje. Standardna predloga create-next-app doda datoteke .env v .gitignore; dokumentacija Next.js opozarja, da jih skoraj nikoli ne smete poslati v repozitorij.

Če še vedno niste prepričani, kaj lahko shranite v izvorne datoteke, začnite z varnostnim pregledom projekta, zgrajenega z umetno inteligenco. Tukaj obravnavamo ožje vprašanje: kam nastaviti konfiguracijo za določeno uvedbo Vercel.

Najprej ugotovite, kje aplikacija bere spremenljivko#

Preden vnesete kakršne koli vrednosti, sestavite seznam imen, brez samih skrivnosti. Za vsako ime morate ugotoviti tri stvari: katero okolje ga uporablja, kje se izvaja koda, ki bere spremenljivko, in kdaj je vrednost potrebna.

Okolje Development je namenjeno lokalnemu razvoju. Preview je za predogledne uvedbe, Production pa za glavno objavljeno različico. Preview ima lahko nastavitve za določeno vejo Git: te preglasijo splošne nastavitve Preview z enakimi imeni.

V projektu Next.js so spremenljivke brez predpone NEXT_PUBLIC_ privzeto na voljo na strežniku. Predpona NEXT_PUBLIC_ omogoča vdelavo vrednosti v JavaScript, dostavljen brskalniku. To je primerno za nastavitev, ki je izrecno javna, na primer oznako različice, ki ni skrivnost, ne pa za zasebni ključ API. Tudi brez te predpone koda aplikacije skrivnosti ne sme ročno posredovati odjemalcu.

Če še niste ugotovili, katero ogrodje uporabljate, prosite agenta, naj ga prepozna iz projektnih datotek. Primerjava ogrodij Astro in Next.js vam lahko pomaga razumeti razlike; pravila NEXT_PUBLIC_ ne morete uporabiti za vsako aplikacijo React.

Konfiguracija gostovanja je ena od nalog pri delu z aplikacijo in agentom umetne inteligence.

Kako dodati spremenljivko v projekt Vercel#

Korake v uradni nadzorni plošči opravite sami. Agenta ne seznanite z resničnim ključem, da bi izpolnil obrazec, in ne priložite posnetka zaslona, na katerem je vidna njegova vrednost.

1. Odprite nadzorno ploščo Vercel in izberite pravi projekt. Ne zanašajte se samo na ujemanje imena repozitorija: preverite, ali konfigurirate aplikacijo, ki jo nameravate odpreti.
2. V stranski vrstici z nastavitvami projekta odprite Environment Variables.
3. V polje Name vnesite ime, ki ga bere aplikacija, na primer SERVICE_API_KEY. To je zgolj primer imena; če koda pričakuje drugo ime, uporabite njegov točen zapis.
4. V polje Value vnesite vrednost iz shrambe poverilnic. Ne vnesite je v izvorno kodo, klepet ali dnevnik preverjanja.
5. Izberite okolje, ki potrebuje to nastavitev. Za preverjanje predogledne različice uporabite Preview, za glavno različico pa Production. Ene skrivnosti ne dodelite samodejno vsem okoljem.
6. Če nastavitev Preview velja za določeno vejo, preverite izbrano vejo in morebitno preglasitev z enakim imenom.
7. Kliknite Save.

Vercel omogoča dostop do spremenljivk projekta med gradnjo in med izvajanjem strežniških funkcij Vercel Functions. Vendar to, da je vrednost na voljo znotraj Vercela, še ne pomeni, da jo lahko pošljete brskalniku: to je odvisno od kode aplikacije in pravil ogrodja.

Zakaj po kliku na Save potrebujete novo uvedbo#

Shranjevanje spremenljivke ne spremeni obstoječih uvedb. Dokumentacija Vercel zahteva ponovno uvedbo projekta, da nova nastavitev doseže različico, ki jo uporabljate.

Če delate prek Gita, lahko ustvarite novo uvedbo Production tako, da pošljete commit v vejo, določeno v Production Branch, uvedbo Preview pa tako, da ga pošljete v drugo vejo. Ne predpostavljajte, da se glavna veja vedno imenuje main: preverite nastavitev projekta. To naj bo običajna, dogovorjena izdaja projekta, brez dodajanja skrivne datoteke v commit.

Po začetku uvedbe počakajte, da se gradnja konča, in odprite URL nove uvedbe. Zabeležite njen URL, okolje in vejo. Če preverjate stari URL posamezne uvedbe, se nove nastavitve tam ne bodo prikazale.

Next.js ima še en pogoj: sklici, kot je process.env.NEXT_PUBLIC_RELEASE_LABEL, se med izvajanjem next build zamenjajo z njihovimi vrednostmi. Vrednost je po gradnji določena. Če nastavitev spremenite brez nove gradnje, se že dostavljeni odjemalski JavaScript ne bo prepisal.

Kako preveriti rezultat, ne da bi razkrili ključ#

Začnite z varnim primerom: z izrecno nejavno oznako NEXT_PUBLIC_RELEASE_LABEL z vrednostjo preview-check. To sta primer imena in besedila, ne ključ in ne preizkus, ki bi bil tu opravljen. Če aplikacija Next.js to spremenljivko bere neposredno prek process.env.NEXT_PUBLIC_RELEASE_LABEL, lahko oznako po novi gradnji prikaže na predvidenem mestu v vmesniku. To preverjanje potrdi samo, da je bila javna nastavitev posredovana.

Zasebni ključ preverite drugače. Ne izpišite njegove vrednosti, njenega dela, dolžine ali celotnega process.env. Ne ustvarjajte javnega URL-ja, ki vrne vsebino spremenljivke. Najprej na strežniku preverite samo, ali je nastavitev »prisotna / odsotna«, nato pa ločeno preverite funkcijo aplikacije, ki uporablja storitev. Prisotnost nastavitve ne dokazuje, da je ključ veljaven ali da ima zahtevana dovoljenja.

Rezultate lahko zabeležite brez skrivnosti:

• projekt, okolje in veja se ujemajo s tistimi, ki so bili izbrani med konfiguracijo;
• preverjate URL nove uvedbe, ustvarjene po shranjevanju spremenljivke;
• gradnja je končana, zahtevana funkcija aplikacije pa je bila izvedena z varnimi testnimi podatki;
• skrivnost ni razkrita v brskalniku, odgovorih API, dnevnikih ali pogovorih.

Če funkcija izvede plačilo, pošlje sporočilo ali opravi drugo dejanje s posledicami, uporabite namenski testni način storitve. Preverjanje konfiguracije samo po sebi ne odobri resničnega dejanja.

Kaj preveriti, če je vrednost še vedno undefined#

undefined pomeni, da na tej točki dostopa ni bila pridobljena nobena vrednost. Po vrsti preverite ime, okolje in različico, ne da bi hkrati spreminjali vse nastavitve.

Ko preverite ime, okolje in novo različico, napaka v funkciji še vedno ne dokazuje, da jo povzroča spremenljivka. Raziščite konkretno napako v strežniški kodi, ne da bi objavili diagnostične podatke, ki vsebujejo skrivnosti. Ta vodnik ne obljublja, da bo odpravil vsak odgovor HTTP 500.

Za prehod na lastni strežnik je potreben drugačen postopek: glejte vodnik za uvedbo projekta s Coolify. Imena gumbov in koraki konfiguracije Vercel tam ne veljajo.

Obiščite Ailoot.