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

> Proměnné prostředí, Development/Preview/Production, nové nasazení a bezpečná kontrola klíčů v Next.js bez předávání tajných údajů do prohlížeče.

Source: https://ailoot.ai/blog/cs/vercel-environment-variables/
Canonical: https://ailoot.ai/blog/cs/vercel-environment-variables/
Language: cs
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-229
Revision: sha256-5f5bafc5dda4f141f14654728c00a64fa9678d9233e793c2c59f84b6918cc008


<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Hlavní poznatek z této části">

Hlavní poznatek

Pokud soubor `.env` obsahující vaše tajné údaje není v Gitu, přidejte požadované proměnné do části **Environment Variables** svého projektu ve Vercelu. Vyberte prostředí, uložte nastavení a vytvořte nové nasazení: již nasazené verze se nezmění. V Next.js nepřidávejte k tajnému klíči předponu `NEXT_PUBLIC_`: jeho hodnota bude během sestavení zahrnuta do kódu prohlížeče.

</div>

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

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

| Co ověřit | Možnosti | Proč je to důležité |
|----|----|----|
| Prostředí ve Vercelu | Development, Preview, Production | Nastavení se musí vztahovat na verzi, kterou kontrolujete |
| Kde se proměnná čte | Server nebo prohlížeč | Soukromý klíč nesmí být zahrnut do kódu na straně klienta |
| Kdy se proměnná čte | Při sestavení nebo při spuštění serverové funkce | V Next.js jsou veřejné hodnoty pevně dané během sestavení |

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

| Příznak | Co zkontrolovat |
|----|----|
| Funguje místně, ale ne v Preview | Zda název existuje v nastavení Preview projektu; zda je vybrána jiná větev |
| Preview funguje, ale Production ne | Zda je název nastaven pro Production; zda byla po kliknutí na Save vytvořena nová hlavní verze |
| Jedna větev Preview se chová jinak | Zda je pro danou větev nastavena hodnota se stejným názvem, která přepisuje obecné nastavení |
| Server proměnnou vidí, ale prohlížeč ne | V Next.js je to očekávané u neveřejné proměnné; nepřesouvejte soukromý klíč do prohlížeče |
| Veřejný štítek Next.js má stále starou hodnotu | Zda proběhlo nové sestavení s požadovanou hodnotou; zda otevřená URL patří tomuto nasazení |
| Veřejný název je správný, ale dosazení nefunguje | Zda ji kód čte dynamicky pomocí `process.env[varName]`: Next.js tyto odkazy nevkládá přímo při sestavení |

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](https://ailoot.ai/blog/cs/coolify-claude-code-deploy/). Názvy tlačítek a kroky konfigurace ve Vercelu se na něj nevztahují.

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

### Zdroje

- [Proměnné prostředí ve Vercelu](https://vercel.com/docs/environment-variables)
- [Přidávání a správa proměnných prostředí ve Vercelu](https://vercel.com/docs/environment-variables/managing-environment-variables)
- [Proměnné prostředí v Next.js](https://nextjs.org/docs/app/guides/environment-variables)

</div>





[Přejděte na Ailoot](https://ailoot.ai/).

## Časté otázky

### Proč je proměnná po uložení ve Vercel stále undefined?

Zkontrolujte projekt, prostředí a případný rozsah pro konkrétní větev a vytvořte nové nasazení. Existující nasazení nezískají proměnnou jen tím, že uložíte nové nastavení.

### Mohu přidáním NEXT_PUBLIC_ zpřístupnit tajný údaj aplikaci Next.js?

Tento prefix pro tajný údaj nepoužívejte: při sestavení vloží hodnotu do kódu prohlížeče. Ponechte ji na serveru a přítomnost ověřujte bez vypsání klíče.


## Ailoot · Společnost a její portfolio projektů

Ailoot staví na dlouhodobých provozních zkušenostech, široké klientské základně, stabilních službách a průběžném sledování KPI.

Společnost a její portfolio projektů: miliony zákazníků; měsíční tržby v miliardách.

Ailoot využívá tyto provozní zkušenosti k poskytování přístupu přes API k funkcím AI v produktech zákazníků, agentech, aplikacích a automatizacích.