Vercel: proměnné prostředí bez .env v Gitu

Tento návod je určen pro projekt, který už je hostovaný na Vercelu. Potřebujete přístup k jeho nastavení a musíte vědět, které proměnné aplikace čte. Níže uvedený příklad se týká Next.js; názvy proměnných z jiného frameworku nelze automaticky převzít. Návod vychází z oficiální dokumentace; nebyl ověřen na skutečném účtu.

Praktické informace o používání Ailootu najdete v dokumentaci.

Proč nemusíte přidávat .env do Gitu při nasazení na Vercel?#

Proměnná prostředí je nastavení s názvem a hodnotou, které aplikace dostává odděleně od svého zdrojového kódu. Například název SERVICE_API_KEY umožňuje programu přístup k hodnotě klíče externí služby. Samotný klíč neuvádějte v návodu, v konverzaci s agentem ani v repozitáři.

Next.js může načítat proměnné z místních souborů .env*. Místní soubor a nastavení projektu ve Vercelu jsou však dvě různá místa. Pokud soubor do repozitáře neposíláte, nastavte hodnoty zvlášť na hostingové platformě. Standardní šablona create-next-app přidává soubory .env do .gitignore; dokumentace Next.js varuje, že byste je do repozitáře téměř nikdy neměli odesílat.

Pokud si stále nejste jisti, co lze ukládat do zdrojových souborů, začněte bezpečnostní kontrolou projektu vytvořeného s pomocí AI. Zde řešíme užší otázku: kam nastavit konfiguraci pro konkrétní nasazení na Vercelu.

Nejdřív zjistěte, odkud aplikace proměnnou čte#

Než zadáte jakékoli hodnoty, sestavte seznam názvů, nikoli samotných tajných údajů. U každého názvu je potřeba zjistit tři věci: které prostředí ho používá, kde běží kód, který proměnnou čte, a kdy je hodnota potřeba.

Prostředí Development je určeno pro místní vývoj. Preview slouží pro náhledová nasazení a Production pro hlavní publikovanou verzi. Preview může mít nastavení pro konkrétní větev Gitu: tato nastavení přepisují obecné hodnoty Preview se stejnými názvy.

V projektu Next.js jsou proměnné bez NEXT_PUBLIC_ standardně dostupné na serveru. Předpona NEXT_PUBLIC_ umožňuje vložit hodnotu do JavaScriptu doručeného do prohlížeče. Hodí se pro nastavení, které je výslovně veřejné, například pro nez tajný štítek verze, ale ne pro soukromý klíč API. I bez této předpony nesmí kód aplikace tajný údaj ručně vracet klientovi.

Pokud jste ještě neurčili framework, požádejte agenta, aby ho identifikoval podle souborů projektu. Srovnání Astro a Next.js vám pomůže pochopit rozdíly; pravidlo NEXT_PUBLIC_ nelze použít na každou aplikaci React.

Konfigurace hostingu patří k úkolům při práci na aplikaci s AI agentem.

Jak přidat proměnnou do projektu ve Vercelu?#

Postupujte podle kroků v oficiálním ovládacím panelu sami. Nedávejte agentovi skutečný klíč, aby ho zadal do formuláře, a nepřikládejte snímek obrazovky s jeho hodnotou.

1. Otevřete ovládací panel Vercelu a vyberte správný projekt. Nespoléhejte jen na shodu názvu repozitáře: ověřte, že konfigurujete aplikaci, kterou chcete otevřít.
2. V postranním panelu nastavení projektu přejděte na Environment Variables.
3. Do pole Name zadejte název, který aplikace čte, například SERVICE_API_KEY. Jde o ukázkový název; pokud kód očekává jiný, použijte přesně jeho zápis.
4. Do pole Value zadejte hodnotu ze správce přihlašovacích údajů. Neuvádějte ji ve zdrojovém kódu, chatu ani záznamu o ověření.
5. Vyberte prostředí, které toto nastavení potřebuje. Pro kontrolu náhledové verze použijte Preview a pro hlavní verzi Production. Nepřiřazujte automaticky jeden tajný údaj všem prostředím.
6. Pokud se nastavení Preview vztahuje na konkrétní větev, ověřte vybranou větev a případné přepsání se stejným názvem.
7. Klikněte na Save.

Vercel zpřístupňuje proměnné projektu při sestavení i při běhu Vercel Functions na straně serveru. To, že je hodnota dostupná ve Vercelu, ale neznamená, že ji lze poslat do prohlížeče: záleží na kódu aplikace a pravidlech frameworku.

Proč po kliknutí na Save potřebujete nové nasazení#

Uložení proměnné nezmění existující nasazení. Dokumentace Vercelu vyžaduje opětovné nasazení projektu, aby se nové nastavení dostalo do verze, kterou používáte.

Při práci přes Git můžete vytvořit nové produkční nasazení odesláním commitu do větve uvedené v Production Branch a náhledové nasazení odesláním do jiné větve. Nepředpokládejte, že hlavní větev se vždy jmenuje main: ověřte nastavení svého projektu. Mělo by jít o běžné, dohodnuté vydání projektu bez přidávání souboru s tajnými údaji do commitu.

Po spuštění nasazení počkejte, až se sestavení dokončí, a otevřete URL nového nasazení. Poznamenejte si jeho URL, prostředí a větev. Pokud zkontrolujete starou URL konkrétního nasazení, nové nastavení se tam neprojeví.

V Next.js platí ještě jedna podmínka: odkazy jako process.env.NEXT_PUBLIC_RELEASE_LABEL se nahradí svými hodnotami během next build. Hodnota je po sestavení pevně daná. Změna nastavení bez nového sestavení nepřepíše JavaScript na straně klienta, který už byl doručen.

Jak ověřit výsledek, aniž byste odhalili klíč#

Začněte bezpečným příkladem: výslovně netajný štítek s názvem NEXT_PUBLIC_RELEASE_LABEL a hodnotou preview-check. Jde o ukázkový název a text, nikoli o klíč nebo zde provedený test. Pokud aplikace Next.js čte tuto proměnnou přímo přes process.env.NEXT_PUBLIC_RELEASE_LABEL, může po novém sestavení zobrazit štítek na zamýšleném místě v rozhraní. Tato kontrola pouze potvrzuje, že se veřejné nastavení předalo dál.

Soukromý klíč se ověřuje jinak. Nevypisujte jeho hodnotu, její část, délku ani celý objekt process.env. Nevytvářejte veřejnou URL, která vrací obsah proměnné. Nejprve na serveru ověřte pouze, zda je nastavení „přítomné / nepřítomné“, a potom samostatně zkontrolujte funkci aplikace, která službu používá. Přítomnost nastavení nedokazuje, že je klíč platný nebo má požadovaná oprávnění.

Výsledky můžete zaznamenat bez tajných údajů:

• projekt, prostředí a větev odpovídají těm, které jste vybrali při konfiguraci;
• kontrolujete URL nového nasazení vytvořeného po uložení proměnné;
• sestavení je dokončené a požadovaná funkce aplikace byla spuštěna s bezpečnými testovacími daty;
• tajný údaj není odhalen v prohlížeči, odpovědích API, protokolech ani konverzacích.

Pokud funkce provádí platbu, odesílá zprávu nebo vykonává jinou činnost s důsledky, použijte určený testovací režim služby. Samotná kontrola konfigurace neopravňuje k provedení skutečné operace.

Co zkontrolovat, pokud je hodnota stále undefined#

undefined znamená, že v daném místě přístupu nebyla získána žádná hodnota. Postupně ověřujte název, prostředí a verzi, aniž byste měnili všechna nastavení najednou.

Jakmile ověříte název, prostředí a novou verzi, chyba ve funkci stále nedokazuje, že ji způsobila proměnná. Prošetřete konkrétní chybu kódu na straně serveru, aniž byste zveřejnili diagnostická data obsahující tajné údaje. Tento návod neslibuje vyřešení každé odpovědi HTTP 500.

Přechod na vlastní server vyžaduje jiný postup: podívejte se na návod k nasazení projektu pomocí Coolify. Názvy tlačítek a kroky konfigurace ve Vercelu se na něj nevztahují.

Přejděte na Ailoot.