Vercel: környezeti változók a .env Gitbe helyezése nélkül

Ez az útmutató egy már Vercelen üzemeltetett projekthez készült. Hozzá kell férned a beállításaihoz, és tudnod kell, mely változókat olvassa az alkalmazás. Az alábbi példa Next.js-re vonatkozik; más keretrendszer változónevei nem vihetők át automatikusan. Az útmutató hivatalos dokumentáció alapján készült; valódi fiókon nem tesztelték.

Az Ailoot használatával kapcsolatos gyakorlati információkat a dokumentációban találod.

Miért nem kell hozzáadnod a .env fájlt a Githez#

A környezeti változó olyan beállítás, amelynek neve és értéke van, és amelyet az alkalmazás a forráskódjától külön kap meg. Például a SERVICE_API_KEY név lehetővé teszi, hogy a program hozzáférjen egy külső szolgáltatás kulcsának értékéhez. Magát a kulcsot ne tedd bele az útmutatóba, az ügynökkel folytatott beszélgetésbe vagy a tárolóba.

A Next.js be tudja tölteni a változókat a helyi .env* fájlokból. A helyi fájl és a Vercelben lévő projektbeállítások azonban két külön helyen találhatók. Ha a fájlt nem töltöd fel a tárolóba, az értékeket külön kell beállítanod a tárhelyszolgáltató platformján. A szabványos create-next-app sablon hozzáadja a .env fájlokat a .gitignore-hoz; a Next.js dokumentációja figyelmeztet, hogy ezeket szinte soha nem szabad feltölteni a tárolóba.

Ha még nem vagy biztos benne, mi tárolható a forrásfájlokban, kezdd a mesterséges intelligenciával készült projekt biztonsági ellenőrzésével. Itt egy szűkebb kérdéssel foglalkozunk: hol kell beállítani egy adott Vercel-telepítés konfigurációját.

Először állapítsd meg, hol olvassa az alkalmazás a változót#

Mielőtt bármilyen értéket megadnál, készíts listát a nevekről, maguk a titkok nélkül. Minden névnél három dolgot kell megállapítanod: melyik környezet használja, hol fut a változót olvasó kód, és mikor van szükség az értékre.

A Development környezet helyi fejlesztésre szolgál. A Preview az előnézeti telepítésekhez, a Production pedig a fő, közzétett verzióhoz való. A Preview rendelkezhet egy adott Git-ágra vonatkozó beállításokkal: ezek felülírják az azonos nevű általános Preview-beállításokat.

Egy Next.js-projektben a NEXT_PUBLIC_ előtag nélküli változók alapértelmezés szerint elérhetők a szerveren. A NEXT_PUBLIC_ előtag lehetővé teszi, hogy az érték beágyazódjon a böngészőbe küldött JavaScriptbe. Ez olyan beállításhoz megfelelő, amely kifejezetten nyilvános, például egy nem titkos verziócímkéhez, de privát API-kulcshoz nem. Az előtag nélkül sem adhatja vissza az alkalmazás kódja kézzel a titkot a kliensnek.

Ha még nem azonosítottad a keretrendszert, kérd meg az ügynököt, hogy állapítsa meg a projektfájlok alapján. Az Astro és a Next.js összehasonlítása segíthet megérteni a különbségeket; a NEXT_PUBLIC_ szabály nem alkalmazható minden React-alkalmazásra.

A tárhely konfigurálása is azok közé a feladatok közé tartozik, amelyekkel egy mesterséges intelligenciával dolgozó alkalmazás fejlesztése során foglalkozni kell.

Változó hozzáadása egy Vercel-projekthez#

A lépéseket te magad végezd el a hivatalos irányítópulton. Ne adj valódi kulcsot az ügynöknek az űrlap kitöltéséhez, és ne csatolj olyan képernyőképet, amelyen látható az értéke.

1. Nyisd meg a Vercel irányítópultját, és válaszd ki a megfelelő projektet. Ne hagyatkozz kizárólag arra, hogy a tároló neve egyezik: ellenőrizd, hogy azt az alkalmazást konfigurálod-e, amelyet meg akarsz nyitni.
2. Nyisd meg a projekt beállításainak oldalsávjában az Environment Variables részt.
3. A Name mezőbe írd be az alkalmazás által olvasott nevet, például SERVICE_API_KEY. Ez egy példaértékű név; ha a kód más nevet vár, pontosan annak megfelelően írd be.
4. A Value mezőbe írd be a hitelesítő adatok tárolójában lévő értéket. Ne tedd bele a forráskódba, csevegésbe vagy ellenőrzési naplóba.
5. Válaszd ki azt a környezetet, amelynek szüksége van erre a beállításra. Előnézeti verzió ellenőrzéséhez a Preview, a fő verzióhoz a Production lehetőséget használd. Ne rendeld automatikusan ugyanazt a titkot minden környezethez.
6. Ha a Preview-beállítás egy adott ágra vonatkozik, ellenőrizd a kiválasztott ágat és az azonos nevű felülíró beállítást.
7. Kattints a Save gombra.

A Vercel elérhetővé teszi a projektváltozókat a build során és a Vercel Functions szerveroldali futásakor is. Az azonban, hogy egy érték elérhető a Vercelben, nem jelenti azt, hogy elküldhető a böngészőnek: ez az alkalmazás kódjától és a keretrendszer szabályaitól függ.

Miért kell új telepítés a Save után#

Egy változó mentése nem módosítja a meglévő telepítéseket. A Vercel dokumentációja szerint újra kell telepítened a projektet, hogy az új beállítás érvénybe lépjen az általad használt verzióban.

Ha Git-en keresztül dolgozol, új Production-telepítést hozhatsz létre úgy, hogy commitot küldesz a Production Branch mezőben megadott ágra, Preview-telepítést pedig egy másik ágra küldött commit segítségével. Ne feltételezd, hogy a fő ág neve mindig main: ellenőrizd a projekt beállítását. Ez egy szokásos, egyeztetett projektkiadás legyen, titkos fájl hozzáadása nélkül a commitban.

A telepítés elindítása után várd meg a build befejezését, majd nyisd meg az új telepítés URL-jét. Jegyezd fel az URL-t, a környezetet és az ágat. Ha egy korábbi, egyedi telepítés régi URL-jét ellenőrzöd, az új beállítások ott nem jelennek meg.

A Next.js-nek van egy további feltétele: az olyan hivatkozások, mint a process.env.NEXT_PUBLIC_RELEASE_LABEL, a next build során a megfelelő értékre cserélődnek. Az érték a build után rögzül. Ha új build nélkül módosítod a beállítást, azzal nem íródik át a már elküldött kliensoldali JavaScript.

Az eredmény ellenőrzése a kulcs felfedése nélkül#

Kezdd egy biztonságos példával: egy kifejezetten nem titkos, NEXT_PUBLIC_RELEASE_LABEL nevű címkével, amelynek értéke preview-check. Ezek példaértékű név és szöveg, nem kulcs és nem egy itt elvégzett teszt. Ha egy Next.js-alkalmazás közvetlenül a process.env.NEXT_PUBLIC_RELEASE_LABEL segítségével olvassa ezt a változót, új build után a felület megfelelő helyén megjelenítheti a címkét. Ez az ellenőrzés csak azt igazolja, hogy a nyilvános beállítás átadódott.

A privát kulcsot másképp kell ellenőrizni. Ne jelenítsd meg az értékét, annak egy részét, a hosszát vagy a teljes process.env objektumot. Ne hozz létre olyan nyilvános URL-t, amely visszaadja a változó tartalmát. Először csak azt ellenőrizd, hogy a beállítás „jelen van / hiányzik”-e a szerveren, majd külön vizsgáld meg az alkalmazásnak azt a függvényét, amely a szolgáltatást használja. A beállítás megléte nem bizonyítja, hogy a kulcs érvényes vagy rendelkezik a szükséges jogosultságokkal.

A titkok rögzítése nélkül is feljegyezheted az eredményeket:

• a projekt, a környezet és az ág megegyezik a konfiguráláskor kiválasztottakkal;
• a változó mentése után létrehozott új telepítés URL-jét ellenőrzöd;
• a build befejeződött, és a szükséges alkalmazásfüggvény biztonságos tesztadatokkal lefutott;
• a titok nem szivárgott ki a böngészőbe, API-válaszokba, naplókba vagy beszélgetésekbe.

Ha a függvény fizetést hajt végre, üzenetet küld vagy más következményekkel járó műveletet végez, a szolgáltatás kijelölt tesztmódját használd. A konfiguráció ellenőrzése önmagában nem engedélyez egy valódi műveletet.

Mit ellenőrizz, ha az érték továbbra is undefined#

Az undefined azt jelenti, hogy az adott hozzáférési ponton nem érkezett érték. Sorban ellenőrizd a nevet, a környezetet és a verziót, és ne módosítsd egyszerre az összes beállítást.

Miután ellenőrizted a nevet, a környezetet és az új verziót, a függvényben jelentkező hiba még nem bizonyítja, hogy a változó okozza. Vizsgáld meg a szerveroldali kód konkrét hibáját anélkül, hogy titkokat tartalmazó diagnosztikai adatokat tennél közzé. Ez az útmutató nem ígéri, hogy minden HTTP 500-as választ megold.

A saját szerverre költözéshez más eljárás szükséges: lásd a Coolify-jal történő projekttelepítésről szóló útmutatót. A Vercel gombnevei és konfigurációs lépései arra nem érvényesek.

Ugrás az Ailootra.