Zmienne środowiskowe w Next.js: .env, NEXT_PUBLIC_ | We.Inc
Jak Next.js wczytuje pliki .env i w jakiej kolejności, co naprawdę robi NEXT_PUBLIC_ podczas builda i jak odczytywać wartości w runtime. Wklej swój .env, aby zobaczyć, co trafia do przeglądarki.
Next.js wczytuje pliki .env z katalogu głównego projektu do process.env. Zmienne są domyślnie dostępne tylko na serwerze. Dodaj do nazwy prefiks NEXT_PUBLIC_, a Next.js skopiuje jej wartość do JavaScriptu przeglądarki podczas next build, więc staje się publiczna i zamrożona aż do kolejnego builda. Nigdy nie umieszczaj sekretu pod tym prefiksem.
Kolejność wczytywania: wygrywa pierwszy plik, który definiuje zmienną
Kolejność
Źródło
Uwagi
Wartości już ustawione przez powłokę lub hosting zawsze wygrywają
.env.$(NODE_ENV).local
Na przykład .env.development.local
.env.local
Pomijany, gdy NODE_ENV to test
.env.$(NODE_ENV)
Na przykład .env.production
.env
Wspólne wartości domyślne dla każdego środowiska
Wklej poniżej zawartość pliku .env. Narzędzie przypisze każdą zmienną do kategorii tylko serwer lub wysyłane do przeglądarki i oznaczy publiczne nazwy, które wyglądają na sekrety. Wszystko działa na tej stronie; nic z tego, co wkleisz, nie jest wysyłane.
Wklej linie z .env do pola albo edytuj przykład.
Przeczytaj tabelę: każda zmienna jest oznaczona jako tylko serwer lub wysyłana do przeglądarki.
Zareaguj na każde ostrzeżenie, na przykład nazwę NEXT_PUBLIC_ zawierającą KEY, SECRET lub TOKEN.
Po zmianie dowolnej wartości NEXT_PUBLIC_ zbuduj projekt ponownie, bo stara wartość jest wpieczona w paczkę.
Trzymaj pliki .env w katalogu głównym projektu, nawet gdy kod jest w folderze src. Next.js nie szuka ich wewnątrz src.
Commituj .env i .env.test z bezpiecznymi wartościami domyślnymi, jeśli zespół tego chce, ale nigdy nie commituj plików .env*.local.
Odczytuj zmienne publiczne po pełnej, dosłownej nazwie. process.env[name] ani zdestrukturyzowane process.env nie są podmieniane podczas builda.
Potrzebujesz jednego obrazu Docker dla stagingu i produkcji? Odczytuj zmienne serwerowe podczas dynamicznego renderowania, a to, czego potrzebuje przeglądarka, przekazuj w dół jako propsy.
Użyj loadEnvConfig z @next/env, aby wczytać te same pliki w konfiguracji ORM, skrypcie lub konfiguracji testów poza Next.js.
Najczęściej zadawane pytania
Dlaczego moja zmienna środowiskowa ma wartość undefined w przeglądarce?
Bez prefiksu NEXT_PUBLIC_ zmienna istnieje tylko na serwerze, a Next.js zastępuje ją pustym ciągiem w kodzie klienta. Dodaj prefiks tylko wtedy, gdy wartość można bezpiecznie opublikować, a potem zbuduj projekt ponownie.
Zmieniłem wartość NEXT_PUBLIC_ na hostingu i nic się nie stało. Dlaczego?
Wartości publiczne są wstawiane do kodu podczas next build. Wdrożona paczka zachowuje starą wartość, dopóki nie zbudujesz jej ponownie z nową.
Czy .env.local działa w testach?
Nie. Gdy NODE_ENV to test, Next.js pomija .env.local, aby każde uruchomienie testów dostawało te same wartości. Wartości domyślne dla testów umieść w .env.test, a własne nadpisania w .env.test.local.
Czy jedna zmienna może odwoływać się do innej?
Tak. Wpisz $OTHER_NAME w wartości, a Next.js ją rozwinie. Jeśli wartość wymaga dosłownego znaku dolara, poprzedź go znakiem ucieczki: \$.
Na co jest ustawione NODE_ENV?
Jeśli go nie ustawisz, next dev używa development, a pozostałe polecenia production. Dozwolone wartości to production, development i test.
Co naprawdę robi NEXT_PUBLIC_
Prefiks to instrukcja dla bundlera. Podczas next build każde dosłowne process.env.NEXT_PUBLIC_SOMETHING w Twoim kodzie jest zastępowane wartością ze środowiska, w którym działał build, a ten tekst trafia do plików JavaScript, które każdy może pobrać.
Ma to dwie konsekwencje. Po pierwsze, zmienna publiczna nigdy nie jest tajna, niezależnie od nazwy pliku. Po drugie, jest zamrożona: przeniesienie jednego builda ze stagingu na produkcję zabiera ze sobą wartość ze stagingu.
Odczytywanie wartości w runtime
Kod serwerowy może odczytać dowolną zmienną, publiczną lub nie. Aby mieć pewność, że wartość jest odczytywana przy każdym żądaniu, a nie podczas builda, renderuj stronę dynamicznie, na przykład wywołując await connection() z next/server przed odczytaniem process.env.
Przeglądarka w ogóle nie może odczytać zmiennych serwerowych. Jeśli Client Component potrzebuje wartości z runtime, pobierz ją z własnego Route Handlera lub przekaż jako props z Server Component.
Zabezpiecz się przed wyciekami
Funkcję pomocniczą, która czyta klucz API, można przez przypadek zaimportować do Client Component. Dodaj import 'server-only' na początku takich plików, a build się nie powiedzie, jeśli plik kliencki je zaimportuje.
Odczytywanie zmiennych w kodzie
Wartość tylko serwerowa w Route Handlerze
DB_URL nie ma prefiksu, więc istnieje tylko na serwerze. Route Handlers i Server Components mogą ją swobodnie odczytywać.
Wartość publiczna w Client Component
Wymagana jest pełna, dosłowna nazwa. Podczas builda Next.js podmienia ją na wartość, więc przeglądarka widzi zwykły ciąg znaków.
Odczyt wartości przy każdym żądaniu
await connection() sprawia, że strona renderuje się dynamicznie, więc wartość pochodzi z działającego serwera, a nie z builda.
loadEnvConfig stosuje tę samą kolejność wczytywania, dzięki czemu skrypty i konfiguracje testów pozostają zgodne z aplikacją.
Sprawdzarka .env
Wklej linie z .env
Gdzie można odczytać każdą zmienną
Zmienna
Dostępna w
Uwaga
Tylko serwer
Serwer i przeglądarka (wstawiana podczas builda)
To nie jest linia ze zmienną
Nazwa wygląda na sekret. Wszystko z NEXT_PUBLIC_ jest widoczne dla każdego odwiedzającego.
Odwołuje się do {v}, które Next.js rozwija.
NODE_ENV przyjmuje tylko production, development lub test.