Jump to content

Zmienne Środowiskowe

Create T3 App korzysta z paczki ZodÔćŚ w celu walidacji twoich zmiennych ┼Ťrodowiskowych podczas runtimeÔÇÖu oraz budowania aplikacji. Do┼é─ůczane s─ů z tego powodu dodatkowe pliki w folderze env:

­čôü src/env

Ôöú ­čôä client.mjs

Ôöú ­čôä schema.mjs

Ôöú ­čôä server.mjs

Ich zawarto┼Ť─ç mo┼╝e na pocz─ůtku wygl─ůda─ç strasznie, ale nie martw si─Ö. Nie jest to tak skomplikowane, jak mo┼╝e Ci si─Ö wydawa─ç. Przyjrzyjmy si─Ö ka┼╝demu z nich po kolei i przejd┼║my przez proces dodawania nowej zmiennej ┼Ťrodowiskowej.

TLDR; Je┼╝eli chcesz doda─ç now─ů zmienn─ů ┼Ťrodowiskow─ů, musisz doda─ç j─ů zar├│wno do pliku .env jak i zdefiniowa─ç walidator w pliku env/schema.mjs.

schema.mjs

Jest to plik, kt├│ry faktycznie b─Ödziesz edytowa─ç. Zawiera dwa schematy, jeden dla zmiennych ┼Ťrod. po stronie serwera, a drugi dla tych po stronie klienta (obiekt clientEnv).

env/schema.mjs
export const serverSchema = z.object({
  // DATABASE_URL: z.string().url(),
});

export const clientSchema = z.object({
  // NEXT_PUBLIC_WS_KEY: z.string(),
});

Schemat Dla Serwera

Zdefiniuj tutaj zmienne ┼Ťrodowiskowe dla serwera.

Koniecznie nie prefixuj tutejszych kluczy NEXT_PUBLIC_. Je┼╝eli to zrobisz, walidacja nie zadzia┼éa, pomagaj─ůc ci w wykryciu niew┼éa┼Ťciwej konfiguracji.

Schemat Dla Klienta

Zdefiniuj tutaj zmienne ┼Ťrodowiskowe dla klienta.

Aby ujawni─ç zmienne dla klienta dodaj prefix NEXT_PUBLIC. Je┼╝eli tego nie zrobisz, walidacja nie zadzia┼éa, pomagaj─ůc ci w wykryciu niew┼éa┼Ťciwej konfiguracji.

// ÔŁî To nie zadzia┼éa, musimy r─Öcznie "rozbi─ç" `process.env`
const schema = z.object({
  NEXT_PUBLIC_WS_KEY: z.string(),
});

const validated = schema.parse(process.env);

server.mjs & client.mjs

To tutaj zachodzi walidacja i eksport poprawnych obiekt├│w. Nie powinna zaj┼Ť─ç potrzeba ich edycji.

Korzystanie Ze Zmiennych Środowiskowych

Je┼╝eli chcesz skorzysta─ç ze swoich zmiennych ┼Ťrodowiskowych, mo┼╝esz zaimportowa─ç je z pliku env/client.mjs lub env/server.mjs, w zale┼╝no┼Ťci od tego, gdzie chcesz u┼╝ywa─ç tych zmiennych:

pages/api/hello.ts
import { env } from "../../env/server.mjs";

// `env` jest w pełni typesafe i pozwala na autouzupełnianie
const dbUrl = env.DATABASE_URL;

.env.example

Poniewa┼╝ plik .env nie jest wrzucany na system kontroli wersji, do┼é─ůczamy tak┼╝e plik .env.example, w kt├│rym - jesli chcesz - mo┼╝esz zawrze─ç kopi─Ö pliku .env z usuni─Ötymi secretami. Nie jest to wymagane, jednak polecamy trzyma─ç aktualn─ů kopi─Ö przyk┼éadowego pliku, aby u┼éatwi─ç potencjalnym kontrybutorom rozpocz─Öcie pracy w ich ┼Ťrodowisku.

Niekt├│re frameworki i narz─Ödzia do budowania, takie jak Next.js, zalecaj─ů przechowywanie sekretnych warto┼Ťci w pliku .env.local i commitowanie plik├│w .env do projektu. Nie jest to przez nas jednak rekomendowane, poniewa┼╝ mo┼╝e to ┼éatwo prowadzi─ç do przypadkowego ujawnienia tych warto┼Ťci. Polecamy natomiast przechowywanie sekretnych warto┼Ťci w pliku .env, trzymanie pliku tego w .gitignore i commitowanie jedynie plik├│w .env.example.

Dodawanie Zmiennych Środowiskowych

Aby upewni─ç si─Ö, ┼╝e tw├│j projekt nie zbuduje si─Ö bez wymaganych zmiennych ┼Ťrod., b─Ödziesz musia┼é doda─ç now─ů zmienn─ů w dw├│ch miejscach:

­čôä .env: Wprowad┼║ swoj─ů zmienn─ů ┼Ťrod. tak, jak to zwykle robisz (np. KLUCZ=WARTO┼Ü─ć)

­čôä schema.mjs: Dodaj odpowiadaj─ůc─ů jej logik─Ö walidacji definiuj─ůc schemat Zod, np. KLUCZ: z.string()

Opcjonalnie mo┼╝esz zaktualizowa─ç plik .env.example:

­čôä .env.example: Wprowad┼║ swoj─ů zmienn─ů ┼Ťrod., upewnij si─Ö jednak ┼╝e nie nie posiada ona warto┼Ťci, kt├│ra jest sekretna, np. KLUCZ=WARTO┼Ü─ć lub KLUCZ=

Przykład

Chc─Ö doda─ç m├│j token do API Twittera jako zmienn─ů ┼Ťrodowiskow─ů po stronie serwera

  1. Dodaj zmienn─ů ┼Ťrod. do pliku .env:
TWITTER_API_TOKEN=1234567890
  1. Dodaj zmienn─ů ┼Ťrodowiskow─ů do pliku schema.mjs:
export const serverSchema = z.object({
  // ...
  TWITTER_API_TOKEN: z.string(),
});

UWAGA: Pusty string to dalej string, wi─Öc z.string() zaakceptuje ka┼╝dy pusty tekst jako poprawn─ů warto┼Ť─ç. Je┼╝eli chcesz, by warto┼Ť─ç by┼éa wymagana (i nie pusta!), mo┼╝esz u┼╝y─ç z.string().min(1).

  1. opcjonalnie: Dodaj zmienn─ů ┼Ťrodowiskow─ů do .env.example. Usu┼ä jednak token.
TWITTER_API_TOKEN=

Recent Contributors To This Page