Zmienne środowiskowe w Next.js wyjaśnione

Zmienne środowiskowe w Next.js

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.

Nie znaleziono jeszcze zmiennych.

Tylko serwer: {n}, wysyłane do przeglądarki: {v}

Zbuduj stronę za darmo · Za darmo, bez karty

Powiązane: Poradniki

Produkt

Dla kogo

Funkcje

Zasoby

Firma

Mapa strony