Vercel: zmienne środowiskowe bez pliku .env w Git

Ten poradnik jest przeznaczony dla projektu, który jest już hostowany w Vercel. Potrzebujesz dostępu do jego ustawień i wiedzy o tym, które zmienne odczytuje aplikacja. Poniższy przykład dotyczy Next.js; nazw zmiennych z innego frameworka nie można automatycznie zastosować. Poradnik opiera się na oficjalnej dokumentacji; nie został przetestowany na prawdziwym koncie.

Praktyczne informacje o korzystaniu z Ailoot znajdziesz w dokumentacji.

Dlaczego nie trzeba dodawać .env do Git#

Zmienna środowiskowa to ustawienie składające się z nazwy i wartości, które aplikacja otrzymuje oddzielnie od kodu źródłowego. Na przykład nazwa SERVICE_API_KEY umożliwia programowi dostęp do wartości klucza zewnętrznej usługi. Nie umieszczaj samego klucza w poradniku, rozmowie z agentem ani repozytorium.

Next.js może wczytywać zmienne z lokalnych plików .env*. Plik lokalny i ustawienia projektu w Vercel to jednak dwa osobne miejsca. Jeśli plik nie jest wypychany do repozytorium, ustaw wartości osobno na platformie hostingowej. Standardowy szablon create-next-app dodaje pliki .env do .gitignore; dokumentacja Next.js ostrzega, że niemal nigdy nie należy wypychać ich do repozytorium.

Jeśli nadal nie masz pewności, co można przechowywać w plikach źródłowych, zacznij od kontroli bezpieczeństwa projektu zbudowanego z pomocą AI. Tutaj zajmujemy się węższym pytaniem: gdzie ustawić konfigurację dla konkretnego wdrożenia w Vercel.

Gdzie aplikacja na Vercel odczytuje zmienne środowiskowe?#

Zanim wpiszesz jakiekolwiek wartości, sporządź listę nazw, bez samych sekretów. Dla każdej nazwy musisz ustalić trzy rzeczy: w którym środowisku jest używana, gdzie wykonywany jest kod odczytujący zmienną oraz kiedy potrzebna jest jej wartość.

Środowisko Development jest przeznaczone do lokalnego programowania. Preview służy do wdrożeń podglądowych, a Production do głównej opublikowanej wersji. Preview może mieć ustawienia dla konkretnej gałęzi Git: nadpisują one ogólne ustawienia Preview o tych samych nazwach.

W projekcie Next.js zmienne bez prefiksu NEXT_PUBLIC_ są domyślnie dostępne na serwerze. Prefiks NEXT_PUBLIC_ umożliwia osadzenie wartości w kodzie JavaScript dostarczanym do przeglądarki. Nadaje się do ustawienia, które jest jawnie publiczne, na przykład niebędącej sekretem etykiety wersji, ale nie do prywatnego klucza API. Nawet bez tego prefiksu kod aplikacji nie może ręcznie zwracać sekretu do klienta.

Jeśli nie udało Ci się jeszcze ustalić, jakiego frameworka używa projekt, poproś agenta o rozpoznanie go na podstawie plików projektu. Porównanie Astro i Next.js pomoże Ci zrozumieć różnice; reguły NEXT_PUBLIC_ nie można stosować do każdej aplikacji React.

Konfiguracja hostingu jest jednym z zadań związanych z pracą nad aplikacją z agentem AI.

Jak dodać zmienną do projektu Vercel#

Wykonaj te czynności samodzielnie w oficjalnym panelu. Nie przekazuj agentowi prawdziwego klucza, aby wypełnił formularz, ani nie załączaj zrzutu ekranu zawierającego jego wartość.

1. Otwórz panel Vercel i wybierz właściwy projekt. Nie polegaj wyłącznie na zgodności nazwy repozytorium: sprawdź, czy konfigurujesz aplikację, którą zamierzasz otworzyć.
2. Przejdź do Environment Variables w pasku bocznym ustawień projektu.
3. W polu Name wpisz nazwę odczytywaną przez aplikację, na przykład SERVICE_API_KEY. To przykładowa nazwa; jeśli kod oczekuje innej, wpisz ją dokładnie.
4. W polu Value wpisz wartość z magazynu poświadczeń. Nie umieszczaj jej w kodzie źródłowym, czacie ani dzienniku weryfikacji.
5. Wybierz środowisko, które wymaga tego ustawienia. Użyj Preview, aby sprawdzić wersję podglądową, i Production dla wersji głównej. Nie przypisuj automatycznie jednego sekretu do wszystkich środowisk.
6. Jeśli ustawienie Preview dotyczy konkretnej gałęzi, sprawdź wybraną gałąź oraz ewentualne ustawienie o tej samej nazwie, które je nadpisuje.
7. Kliknij Save.

Vercel udostępnia zmienne projektu zarówno podczas kompilacji, jak i w trakcie działania funkcji Vercel Functions po stronie serwera. Dostępność wartości w Vercel nie oznacza jednak, że można przesłać ją do przeglądarki: zależy to od kodu aplikacji i reguł frameworka.

Dlaczego po kliknięciu Save potrzebne jest nowe wdrożenie#

Zapisanie zmiennej nie zmienia istniejących wdrożeń. Dokumentacja Vercel wymaga ponownego wdrożenia projektu, aby nowe ustawienie trafiło do używanej wersji.

Podczas pracy z Git możesz utworzyć nowe wdrożenie Production, wypychając commit do gałęzi wskazanej w Production Branch, a wdrożenie Preview — wypychając commit do innej gałęzi. Nie zakładaj, że główna gałąź zawsze nazywa się main: sprawdź ustawienie projektu. Powinno to być standardowe, uzgodnione wydanie projektu, bez dodawania pliku z sekretem do commita.

Po uruchomieniu wdrożenia poczekaj na zakończenie kompilacji i otwórz URL nowego wdrożenia. Zapisz jego URL, środowisko i gałąź. Jeśli sprawdzisz stary URL konkretnego wdrożenia, nowe ustawienia nie będą tam widoczne.

Next.js stawia jeszcze jeden warunek: odwołania takie jak process.env.NEXT_PUBLIC_RELEASE_LABEL są zastępowane ich wartościami podczas wykonywania next build. Wartość zostaje ustalona po kompilacji. Zmiana ustawienia bez nowej kompilacji nie zmieni kodu JavaScript po stronie klienta, który został już dostarczony.

Jak sprawdzić wynik bez ujawniania klucza#

Zacznij od bezpiecznego przykładu: jawnie niebędącej sekretem etykiety o nazwie NEXT_PUBLIC_RELEASE_LABEL i wartości preview-check. To przykładowa nazwa i tekst, a nie klucz ani test wykonany w tym poradniku. Jeśli aplikacja Next.js odczytuje tę zmienną bezpośrednio przez process.env.NEXT_PUBLIC_RELEASE_LABEL, po nowej kompilacji może wyświetlić etykietę w odpowiednim miejscu interfejsu. To sprawdzenie potwierdza jedynie przekazanie ustawienia publicznego.

Prywatny klucz sprawdza się inaczej. Nie wyświetlaj jego wartości, jej fragmentu, długości ani całego process.env. Nie twórz publicznego adresu URL, który zwraca zawartość zmiennej. Najpierw sprawdź wyłącznie, czy ustawienie po stronie serwera jest „obecne / nieobecne”, a następnie osobno sprawdź funkcję aplikacji, która korzysta z usługi. Obecność ustawienia nie dowodzi, że klucz jest prawidłowy ani że ma wymagane uprawnienia.

Możesz zapisać wyniki bez sekretów:

• projekt, środowisko i gałąź odpowiadają tym wybranym podczas konfiguracji;
• sprawdzasz URL nowego wdrożenia utworzonego po zapisaniu zmiennej;
• kompilacja została zakończona, a wymagana funkcja aplikacji uruchomiła się na bezpiecznych danych testowych;
• sekret nie jest ujawniany w przeglądarce, odpowiedziach API, dziennikach ani rozmowach.

Jeśli funkcja wykonuje płatność, wysyła wiadomość lub podejmuje inne działanie mające konsekwencje, użyj wyznaczonego przez usługę trybu testowego. Samo sprawdzenie konfiguracji nie upoważnia do wykonania rzeczywistej operacji.

Co sprawdzić, jeśli wartość nadal jest undefined#

undefined oznacza, że w danym miejscu dostępu nie uzyskano żadnej wartości. Sprawdź po kolei nazwę, środowisko i wersję, nie zmieniając wszystkich ustawień naraz.

Jeśli po sprawdzeniu nazwy, środowiska i nowej wersji funkcja nadal zgłasza błąd, nie dowodzi to, że przyczyną jest zmienna. Zbadaj konkretny błąd kodu po stronie serwera, nie publikując danych diagnostycznych zawierających sekrety. Ten poradnik nie gwarantuje rozwiązania każdego przypadku odpowiedzi HTTP 500.

Przeniesienie projektu na własny serwer wymaga innej procedury: zobacz poradnik wdrażania projektu z Coolify. Nazwy przycisków i kroki konfiguracji z Vercel nie mają do niego zastosowania.

Przejdź do Ailoot.