---
title: Переменные среды
description: Начало работы с Create T3 App
layout: ../../../layouts/docs.astro
lang: ru
isMdx: true
---

import Callout from "../../../components/docs/callout.tsx";

Create T3 App использует собственный пакет [@t3-oss/env-nextjs](https://env.t3.gg) вместе с [Zod](https://github.com/colinhacks/zod) для валидации переменных среды во время выполнения _и_ во время сборки, предоставляя простую логику в файле `src/env.js`:

## env.js

_TLDR; Если вы хотите добавить новую переменную среды, вам следует добавить валидатор в `src/env.js`, а затем пару ключ-значение в `.env`._

```ts:env.js
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`, который отвечает за создание схемы и будет включать главную логику валидации для клиентских и серверных переменных среды.

<Callout type="info">
  Для получения дополнительной информации о том, как `createEnv` работает
  изнутри, посмотрите документацию [T3 Env](https://env.t3.gg/docs/introduction)
  (EN)
</Callout>

## Использование переменных среды

Когда вы хотите использовать переменные среды, вы можете импортировать их из `env.js` и использовать их как вы обычно использовали бы. Если вы импортируете этот файл на стороне клиента и попробуете получить серверную переменную, вы получите ошибку выполнения:

```ts:pages/api/hello.ts
import { env } from "../../env.js";

// `env` полностью типобезопасно и предоставляет автокомплит
const dbUrl = env.DATABASE_URL;
```

```ts:pages/index.tsx
import { env } from "../env.js";

// ❌ Это даст ошибку
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.js`: Добавьте соответствующую логику валидации для переменных среды, определив для каждой из них Zod схему внутри `createEnv`, например `KEY: z.string()`. Кроме этого, убедитесь в том, что вы деструкткрировали их в опции `runtimeEnv`, например `KEY: process.env.KEY`.

<Callout type="info">
  Зачем нужно деструктурировать переменные среды внутри `runtimeEnv`? Это
  связано с тем, как Next.js собирает переменные среды в некоторых рантаймах.
  Деструктурируя их вручную, мы гарантируем, что эти переменные не будут убраны
  из финальной сборки.
</Callout>

Опционально, вы также можете обновлять файл `.env.example`:

📄 `.env.example`: Введите вашу переменную среды, но убедитесь, что не включаете значение, если оно является секретным, т.е. `KEY=VALUE` или `KEY=`

### Пример

_Я хочу добавить мой Twitter API токен в качестве переменной среды на стороне сервера_

1. Добавьте переменную среды в `.env`:

```
TWITTER_API_TOKEN=1234567890
```

2. Добавьте переменную среды в `env.js`:

```ts
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,
  },
});
```

3. _Опционально:_ Добавьте переменную среды в `.env.example`, но не включайте токен в `runtimeEnv`

```
TWITTER_API_TOKEN=
```
