Attention: This page is 39 days older than the English version and might be outdated. If you're a native speaker of this language and would like to contribute to the project, please consider updating this page to match the latest English version.
You can also view the English version of this page.
Переменные среды
Create T3 App использует собственный пакет @t3-oss/env-nextjs↗ вместе с Zod↗ для валидации переменных среды во время выполнения и во время сборки, предоставляя простую логику в файле src/env.mjs
:
env.mjs
TLDR; Если вы хотите добавить новую переменную среды, вам следует добавить валидатор в src/env.mjs
, а затем пару ключ-значение в .env
.
import { createEnv } from "@t3-oss/env-nextjs";
import { z } from "zod";
export const env = createEnv({
server: {
NODE_ENV: z.enum(["development", "test", "production"]),
},
client: {
// NEXT_PUBLIC_CLIENTVAR: z.string(),
},
runtimeEnv: {
NODE_ENV: process.env.NODE_ENV,
},
});
T3 Env использует createEnv
, который отвечает за создание схемы и будет включать главную логику валидации для клиентских и серверных переменных среды.
Для получения дополнительной информации о том, как createEnv
работает изнутри, посмотрите документацию T3
Env↗ (EN)
Использование переменных среды
Когда вы хотите использовать переменные среды, вы можете импортировать их из env.mjs
и использовать их как вы обычно использовали бы. Если вы импортируете этот файл на стороне клиента и попробуете получить серверную переменную, вы получите ошибку выполнения:
import { env } from "../../env.mjs";
// `env` полностью типобезопасно и предоставляет автокомплит
const dbUrl = env.DATABASE_URL;
import { env } from "../env.mjs";
// ❌ Это даст ошибку
const dbUrl = env.DATABASE_URL;
// ✅ Тут все ОК
const wsKey = env.NEXT_PUBLIC_WS_KEY;
.env.example
Из-за того, что файл .env
по умолчанию не добавляется в систему контроля версий, мы также добавили файл .env.example
, в котором вы можете по желанию сохранить копию вашего файла .env
с удаленными секретами. Это необязательно, но мы рекомендуем держать пример в актуальном состоянии, чтобы сделать процесс настройки среды для новых участников проекта как можно проще.
Некоторые фреймворки и инструменты сборки, такие как Next.js, предлагают хранить секреты в файле .env.local
и коммитить файлы .env
в ваш проект. Это не рекомендуется, поскольку это может облегчить случайный коммит секретов в ваш проект. Вместо этого мы рекомендуем хранить секреты в .env
, держать ваш файл .env
в .gitignore
и коммитить только файлы .env.example
в ваш проект.
Добавление переменных среды
Для того, чтобы убедиться, что ваша сборка никогда не завершится без переменных среды, которые проект требует, вам нужно добавить новые переменные среды в двух местах:
📄 .env
: Введите переменную среды, как обычно делаете в файле .env
, т.е. KEY=VALUE
📄 env.mjs
: Добавьте соответствующую логику валидации для переменных среды, определив для каждой из них Zod схему внутри createEnv
, например KEY: z.string()
. Кроме этого, убедитесь в том, что вы деструкткрировали их в опции runtimeEnv
, например KEY: process.env.KEY
.
Зачем нужно деструктурировать переменные среды внутри runtimeEnv
?
Это связано с тем, как Next.js собирает переменные среды в некоторых рантаймах.
Деструктурируя их вручную, мы гарантируем, что эти переменные не будут убраны из финальной сборки.
Опционально, вы также можете обновлять файл .env.example
:
📄 .env.example
: Введите вашу переменную среды, но убедитесь, что не включаете значение, если оно является секретным, т.е. KEY=VALUE
или KEY=
Пример
Я хочу добавить мой Twitter API токен в качестве переменной среды на стороне сервера
- Добавьте переменную среды в
.env
:
TWITTER_API_TOKEN=1234567890
- Добавьте переменную среды в
env.mjs
:
import { createEnv } from "@t3-oss/env-nextjs";
import { z } from "zod";
export const env = createEnv({
server: {
TWITTER_API_TOKEN: z.string(),
},
// ...
runtimeEnv: {
// ...
TWITTER_API_TOKEN: process.env.TWITTER_API_TOKEN,
},
});
Пустая строка все еще является строкой, поэтому z.string()
примет пустую строку как допустимое значение. Если вы хотите убедиться, что переменная среды не пуста, вы можете использовать z.string().min(1)
._
- Опционально: Добавьте переменную среды в
.env.example
, но не включайте токен вruntimeEnv
TWITTER_API_TOKEN=