Vercel: aplinkos kintamieji, kai .env nėra Git

Šis vadovas skirtas projektui, kuris jau talpinamas Vercel. Jums reikia prieigos prie jo nustatymų ir suprasti, kuriuos kintamuosius skaito programa. Toliau pateiktas pavyzdys taikomas Next.js; kitos sistemos kintamųjų pavadinimų negalima automatiškai perkelti. Vadovas parengtas remiantis oficialia dokumentacija; jis nebuvo išbandytas tikroje paskyroje.

Praktinės informacijos apie Ailoot naudojimą rasite dokumentacijoje.

Kodėl nereikia pridėti .env į Git#

Aplinkos kintamasis yra nustatymas, turintis pavadinimą ir reikšmę, kurią programa gauna atskirai nuo savo pirminio kodo. Pavyzdžiui, pavadinimas SERVICE_API_KEY leidžia programai pasiekti išorinės paslaugos rakto reikšmę. Nedėkite paties rakto į vadovą, pokalbį su agentu ar saugyklą.

Next.js gali įkelti kintamuosius iš vietinių .env* failų. Tačiau vietinis failas ir projekto nustatymai Vercel yra dvi atskiros vietos. Jei failas nėra įkeltas į saugyklą, reikšmes atskirai nustatykite prieglobos platformoje. Standartinis create-next-app šablonas įtraukia .env failus į .gitignore; Next.js dokumentacijoje įspėjama, kad jų beveik niekada nereikėtų įkelti į saugyklą.

Jei vis dar nesate tikri, ką galima saugoti pirminio kodo failuose, pradėkite nuo saugumo patikros projektui, sukurtam naudojant AI. Čia nagrinėjame siauresnį klausimą: kur nustatyti konkretaus Vercel diegimo konfigūraciją.

Pirmiausia nustatykite, kur programa nuskaito kintamąjį#

Prieš įvesdami reikšmes, sudarykite pavadinimų sąrašą, neįtraukdami pačių paslapčių. Kiekvienam pavadinimui turite nustatyti tris dalykus: kuri aplinka jį naudoja, kur vykdomas kintamąjį nuskaitantis kodas ir kada reikalinga reikšmė.

Development aplinka skirta vietiniam kūrimui. Preview skirta peržiūros diegimams, o Production – pagrindinei paskelbtai versijai. Preview gali turėti konkrečiai Git šakai skirtus nustatymus: jie pakeičia bendruosius Preview nustatymus tokiais pačiais pavadinimais.

Next.js projekte kintamieji be NEXT_PUBLIC_ prefikso pagal numatytuosius nustatymus pasiekiami serveryje. Prefiksas NEXT_PUBLIC_ leidžia įterpti reikšmę į naršyklei pateikiamą JavaScript kodą. Tai tinka aiškiai viešam nustatymui, pavyzdžiui, neviešos paslapties neturinčiai versijos žymai, bet ne privačiam API raktui. Net ir be šio prefikso programos kodas neturi rankiniu būdu grąžinti paslapties klientui.

Jei dar nenustatėte naudojamos sistemos, paprašykite agento ją identifikuoti pagal projekto failus. Astro ir Next.js palyginimas gali padėti suprasti skirtumus; NEXT_PUBLIC_ taisyklės negalima taikyti kiekvienai React programai.

Prieglobos konfigūravimas yra viena iš užduočių dirbant su programa ir AI agentu.

Kaip pridėti kintamąjį prie Vercel projekto#

Veiksmus oficialiame valdymo skydelyje atlikite patys. Neduokite agentui tikro rakto, kad jis užpildytų formą, ir nepridėkite ekrano kopijos, kurioje matoma jo reikšmė.

1. Atidarykite Vercel valdymo skydelį ir pasirinkite tinkamą projektą. Nepasikliaukite vien sutampančiu saugyklos pavadinimu: patikrinkite, ar konfigūruojate programą, kurią ketinate atidaryti.
2. Projekto nustatymų šoninėje juostoje eikite į Environment Variables.
3. Lauke Name įveskite programos nuskaitomą pavadinimą, pavyzdžiui, SERVICE_API_KEY. Tai pavyzdinis pavadinimas; jei kode tikimasi kito, naudokite tiksliai tokį, kokio reikia.
4. Lauke Value įveskite reikšmę iš savo kredencialų saugyklos. Nedėkite jos į pirminį kodą, pokalbį ar tikrinimo žurnalą.
5. Pasirinkite aplinką, kuriai reikalingas šis nustatymas. Peržiūros versijai tikrinti naudokite Preview, o pagrindinei versijai – Production. Automatiškai nepriskirkite vienos paslapties visoms aplinkoms.
6. Jei Preview nustatymas taikomas konkrečiai šakai, patikrinkite pasirinktą šaką ir visus to paties pavadinimo perrašymo nustatymus.
7. Spustelėkite Save.

Vercel leidžia naudoti projekto kintamuosius tiek kūrimo metu, tiek vykdant serverio pusėje veikiančias Vercel Functions. Tačiau tai, kad reikšmė pasiekiama Vercel, nereiškia, kad ją galima siųsti į naršyklę: tai priklauso nuo programos kodo ir sistemos taisyklių.

Kodėl išsaugojus reikia naujo diegimo#

Išsaugojus kintamąjį esami diegimai nepasikeičia. Vercel dokumentacijoje reikalaujama iš naujo įdiegti projektą, kad naujas nustatymas būtų pritaikytas jūsų naudojamai versijai.

Dirbdami per Git, galite sukurti naują Production diegimą nusiuntę commit į šaką, nurodytą Production Branch, o Preview diegimą – nusiuntę commit į kitą šaką. Nemanykite, kad pagrindinė šaka visada yra main: patikrinkite projekto nustatymą. Tai turėtų būti įprastas, suderintas projekto leidimas, į commit nepridedant failo su paslaptimi.

Pradėję diegimą palaukite, kol bus baigtas kūrimas, ir atidarykite naujo diegimo URL. Užsirašykite jo URL, aplinką ir šaką. Jei tikrinsite seno atskiro diegimo URL, nauji nustatymai jame nebus matomi.

Next.js taikoma dar viena sąlyga: nuorodos, pavyzdžiui, process.env.NEXT_PUBLIC_RELEASE_LABEL, per next build pakeičiamos jų reikšmėmis. Po kūrimo reikšmė nebekinta. Pakeitus nustatymą be naujo kūrimo, jau pateiktas kliento pusės JavaScript kodas nebus perrašytas.

Kaip patikrinti rezultatą neatskleidžiant rakto#

Pradėkite nuo saugaus pavyzdžio: aiškiai neslapta žyma pavadinimu NEXT_PUBLIC_RELEASE_LABEL ir reikšme preview-check. Tai pavyzdinis pavadinimas ir tekstas, ne raktas ar čia atliktas testas. Jei Next.js programa nuskaito šį kintamąjį tiesiogiai per process.env.NEXT_PUBLIC_RELEASE_LABEL, po naujo kūrimo ji gali parodyti žymą numatytoje sąsajos vietoje. Šis patikrinimas patvirtina tik tai, kad viešas nustatymas buvo perduotas.

Privatų raktą reikia tikrinti kitaip. Nerodykite jo reikšmės, jos dalies, ilgio ar viso process.env turinio. Nekurkite viešo URL, kuris grąžina kintamojo turinį. Pirmiausia patikrinkite tik tai, ar nustatymas serveryje yra „yra / nėra“, o tada atskirai patikrinkite programos funkciją, kuri naudoja paslaugą. Tai, kad nustatymas yra, neįrodo, jog raktas galioja ar turi reikiamas teises.

Rezultatus galite užfiksuoti neįtraukdami paslapčių:

• projektas, aplinka ir šaka sutampa su pasirinktais konfigūruojant;
• tikrinate naujo diegimo, sukurto išsaugojus kintamąjį, URL;
• kūrimas baigtas, o reikiama programos funkcija įvykdyta naudojant saugius testinius duomenis;
• paslaptis neatskleidžiama naršyklėje, API atsakymuose, žurnaluose ar pokalbiuose.

Jei funkcija atlieka mokėjimą, siunčia pranešimą ar įvykdo kitą pasekmių turintį veiksmą, naudokite tam skirtą paslaugos testavimo režimą. Konfigūracijos patikrinimas pats savaime nesuteikia leidimo atlikti tikrą veiksmą.

Ką tikrinti, jei reikšmė vis dar yra undefined#

undefined reiškia, kad tame prieigos taške reikšmė nebuvo gauta. Tikrinkite pavadinimą, aplinką ir versiją iš eilės, nekeisdami visų nustatymų vienu metu.

Patikrinę pavadinimą, aplinką ir naują versiją, vis tiek negalite teigti, kad kintamasis sukėlė funkcijos klaidą. Ištirkite konkrečią serverio pusės kodo klaidą neskelbdami diagnostinių duomenų, kuriuose yra paslapčių. Šis vadovas negarantuoja, kad padės išspręsti kiekvieną HTTP 500 atsakymą.

Pereiti prie savo serverio reikia pagal kitą procedūrą: žr. projekto diegimo naudojant Coolify vadovą. Vercel mygtukų pavadinimai ir konfigūravimo veiksmai jam netinka.

Atidarykite Ailoot.