Vercel: Premenné prostredia bez .env v Gite

Táto príručka je určená pre projekt, ktorý už je hostovaný na Verceli. Potrebujete prístup k jeho nastaveniam a musíte vedieť, ktoré premenné aplikácia číta. Nasledujúci príklad sa týka Next.js; názvy premenných z iného frameworku nemožno automaticky preniesť. Príručka vychádza z oficiálnej dokumentácie; nebola overená na skutočnom účte.

Praktické informácie o používaní Ailootu nájdete v dokumentácii.

Prečo nemusíte pridávať .env do Gitu#

Premenná prostredia je nastavenie s názvom a hodnotou, ktoré aplikácia dostáva oddelene od svojho zdrojového kódu. Napríklad názov SERVICE_API_KEY umožňuje programu pristupovať k hodnote kľúča externej služby. Samotný kľúč nevkladajte do príručky, konverzácie s agentom ani do repozitára.

Next.js dokáže načítať premenné z lokálnych súborov .env*. Lokálny súbor a nastavenia projektu vo Verceli sú však dve samostatné miesta. Ak súbor nie je odoslaný do repozitára, nastavte hodnoty samostatne na hostingovej platforme. Štandardná šablóna create-next-app pridáva súbory .env do .gitignore; dokumentácia Next.js varuje, že by ste ich takmer nikdy nemali odosielať do repozitára.

Ak si stále nie ste istí, čo možno uložiť do zdrojových súborov, začnite bezpečnostnou kontrolou projektu vytvoreného pomocou AI. Tu sa venujeme užšej otázke: kde nastaviť konfiguráciu pre konkrétne nasadenie na Verceli.

Najprv zistite, odkiaľ aplikácia číta premennú#

Skôr než zadáte akékoľvek hodnoty, vytvorte zoznam názvov bez samotných tajomstiev. Pri každom názve treba zistiť tri veci: ktoré prostredie ho používa, kde sa vykonáva kód, ktorý premennú číta, a kedy je hodnota potrebná.

Prostredie Development je určené na lokálny vývoj. Preview slúži na ukážkové nasadenia a Production na hlavnú publikovanú verziu. Preview môže mať nastavenia pre konkrétnu vetvu Git: tie majú prednosť pred všeobecnými nastaveniami Preview s rovnakými názvami.

V projekte Next.js sú premenné bez predpony NEXT_PUBLIC_ predvolene dostupné na serveri. Predpona NEXT_PUBLIC_ umožňuje vložiť hodnotu do JavaScriptu doručovaného do prehliadača. Hodí sa na nastavenie, ktoré je výslovne verejné, napríklad na neznačkovú menovku verzie, nie však na súkromný kľúč API. Ani bez tejto predpony nesmie kód aplikácie manuálne vrátiť tajomstvo klientovi.

Ak ste ešte nezistili, ktorý framework používate, požiadajte agenta, aby ho určil podľa súborov projektu. Porovnanie Astro a Next.js vám môže pomôcť pochopiť rozdiely; pravidlo NEXT_PUBLIC_ nemožno použiť na každú aplikáciu React.

Konfigurácia hostingu patrí medzi úlohy pri práci na aplikácii s AI agentom.

Ako pridať premennú do projektu Vercel#

Postupujte podľa krokov v oficiálnom ovládacom paneli sami. Nedávajte agentovi skutočný kľúč, aby vyplnil formulár, a neprikladajte snímku obrazovky, na ktorej je viditeľná jeho hodnota.

1. Otvorte ovládací panel Vercel a vyberte správny projekt. Nespoliehajte sa iba na zhodný názov repozitára: overte, že konfigurujete aplikáciu, ktorú chcete otvoriť.
2. V bočnom paneli nastavení projektu prejdite na Environment Variables.
3. Do poľa Name zadajte názov, ktorý aplikácia číta, napríklad SERVICE_API_KEY. Je to ukážkový názov; ak kód očakáva iný, použite jeho presný zápis.
4. Do poľa Value zadajte hodnotu z úložiska prihlasovacích údajov. Nevkladajte ju do zdrojového kódu, chatu ani záznamu o overení.
5. Vyberte prostredie, ktoré toto nastavenie potrebuje. Na kontrolu ukážkovej verzie použite Preview a na hlavnú verziu Production. Nepriraďujte automaticky jedno tajomstvo ku všetkým prostrediam.
6. Ak sa nastavenie Preview vzťahuje na konkrétnu vetvu, skontrolujte vybranú vetvu a prípadné prepísanie s rovnakým názvom.
7. Kliknite na Save.

Vercel sprístupňuje premenné projektu počas zostavovania aj pri spustení serverových funkcií Vercel. To, že je hodnota dostupná v rámci Vercelu, však neznamená, že ju možno odoslať do prehliadača: závisí to od kódu aplikácie a pravidiel frameworku.

Prečo po kliknutí na Save potrebujete nové nasadenie#

Uložením premennej sa existujúce nasadenia nezmenia. Dokumentácia Vercelu vyžaduje opätovné nasadenie projektu, aby sa nové nastavenie dostalo do verzie, ktorú používate.

Pri práci cez Git môžete vytvoriť nové nasadenie Production odoslaním commitu do vetvy určenej v Production Branch a nasadenie Preview odoslaním commitu do inej vetvy. Nepredpokladajte, že hlavná vetva sa vždy volá main: skontrolujte nastavenie projektu. Malo by ísť o bežné, dohodnuté vydanie projektu bez pridania súboru s tajomstvom do commitu.

Po spustení nasadenia počkajte na dokončenie zostavenia a otvorte URL adresu nového nasadenia. Zaznamenajte si jeho URL adresu, prostredie a vetvu. Ak skontrolujete starú URL adresu konkrétneho nasadenia, nové nastavenia sa tam neprejavia.

Next.js má ešte jednu podmienku: odkazy ako process.env.NEXT_PUBLIC_RELEASE_LABEL sa počas next build nahradia svojimi hodnotami. Po zostavení je hodnota pevne daná. Zmena nastavenia bez nového zostavenia nezmení JavaScript na strane klienta, ktorý už bol doručený.

Ako skontrolovať výsledok bez odhalenia kľúča#

Začnite bezpečným príkladom: výslovne neverejnou menovkou s názvom NEXT_PUBLIC_RELEASE_LABEL a hodnotou preview-check. Ide o ukážkový názov a text, nie o kľúč ani o test vykonaný v rámci tejto príručky. Ak aplikácia Next.js číta túto premennú priamo cez process.env.NEXT_PUBLIC_RELEASE_LABEL, po novom zostavení môže zobraziť menovku na určenom mieste rozhrania. Táto kontrola potvrdzuje iba to, že sa verejné nastavenie prenieslo.

Súkromný kľúč sa kontroluje inak. Nevypisujte jeho hodnotu, jej časť, dĺžku ani celý obsah process.env. Nevytvárajte verejnú URL adresu, ktorá vráti obsah premennej. Najprv na serveri skontrolujte iba to, či je nastavenie „prítomné / neprítomné“, a potom samostatne skontrolujte funkciu aplikácie, ktorá používa danú službu. Prítomnosť nastavenia nedokazuje, že je kľúč platný alebo že má požadované oprávnenia.

Výsledky môžete zaznamenať bez tajomstiev:

• projekt, prostredie a vetva zodpovedajú tým, ktoré boli vybrané pri konfigurácii;
• kontrolujete URL adresu nového nasadenia vytvoreného po uložení premennej;
• zostavenie sa dokončilo a požadovaná funkcia aplikácie sa spustila s bezpečnými testovacími údajmi;
• tajomstvo sa neodhaľuje v prehliadači, odpovediach API, záznamoch ani konverzáciách.

Ak funkcia uskutočňuje platbu, odosiela správu alebo vykonáva inú činnosť s dôsledkami, použite určený testovací režim služby. Samotná kontrola konfigurácie neoprávňuje na skutočnú operáciu.

Čo skontrolovať, ak je hodnota stále undefined#

undefined znamená, že v danom mieste prístupu nebola získaná žiadna hodnota. Postupne skontrolujte názov, prostredie a verziu a nemeňte všetky nastavenia naraz.

Po skontrolovaní názvu, prostredia a novej verzie chyba vo funkcii stále nedokazuje, že ju spôsobila premenná. Preskúmajte konkrétnu chybu v kóde na strane servera bez zverejnenia diagnostických údajov obsahujúcich tajomstvá. Táto príručka nesľubuje, že vyrieši každú odpoveď HTTP 500.

Prechod na vlastný server si vyžaduje iný postup: pozrite si príručku o nasadení projektu pomocou Coolify. Názvy tlačidiel a kroky konfigurácie Vercelu sa naň nevzťahujú.

Prejdite na Ailoot.