Jump to content

Переменные среды

Create-T3-App использует Zod для проверки переменных среды во время выполнения и во время сборки, предоставляя дополнительные файлы в директории env:

📁 src/env

┣ 📄 client.mjs

┣ 📄 schema.mjs

┣ 📄 server.mjs

Содержимое этих файлов может показаться страшным на первый взгляд, но не волнуйтесь, это не так сложно, как кажется. Давайте посмотрим на них по одному и пройдемся по процессу добавления дополнительных переменных среды.

Короче; Если вы хотите добавить новую переменную среды, вы должны добавить ее как в .env, так и определить валидатор в env/schema.mjs.

schema.mjs

Это файл с которым вы будете работать. Он содержит две схемы, одну для переменных среды на стороне сервера, а другую для клиента, а также объект clientEnv.

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

export const serverEnv = {
  // DATABASE_URL: process.env.DATABASE_URL,
};

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

export const clientEnv = {
  // NEXT_PUBLIC_WS_KEY: process.env.NEXT_PUBLIC_WS_KEY,
};

Схема сервера

Определите схему переменных среды на стороне сервера здесь.

Убежитесь что вы не добавляете префикс NEXT_PUBLIC к ключам. Валидация не пройдет, если вы это сделаете, чтобы помочь вам обнаружить неверную конфигурацию.

Схема клиента

Определите схему переменных среды на стороне клиента здесь.

Для того, чтобы экспортировать их клиенту, вам нужно добавить префикс NEXT_PUBLIC. Валидация не пройдет, если вы этого не сделаете, чтобы помочь вам обнаружить неверную конфигурацию.

Объект clientEnv

Деструктурируйте process.env здесь.

Нам нужен объект JavaScript, который мы можем деструктурировать нашими схемами Zod и из-за того, как Next.js обрабатывает переменные среды, вы не можете деструктурировать process.env как обычный объект, поэтому нам нужно сделать это вручную.

TypeScript поможет вам убедиться, что вы ввели ключи в clientEnv и clientSchema.

// ❌ This doesn't work, we need to destruct it manually
const schema = z.object({
  NEXT_PUBLIC_WS_KEY: z.string(),
});

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

server.mjs & client.mjs

Здесь происходит валидация и экспортируются проверенные объекты. Вам не нужно изменять эти файлы.

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

Когда вы хотите использовать переменные среды, вы можете импортировать их из env/client.mjs или env/server.mjs в зависимости от того, где вы хотите их использовать:

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

// `env` is fully typesafe and provides autocompletion
const dbUrl = env.DATABASE_URL;

.env.example

Изза того, что файл .env по умолчанию не добавляется в систему контроля версий, мы также добавили файл .env.example, в котором вы можете по желанию сохранить копию вашего файла .env с удаленными секретами. Это не обязательно, но мы рекомендуем держать пример в актуальном состоянии, чтобы сделать процесс настройки среды для новых участников проекта как можно проще. Некоторые фреймворки и инструменты сборки, такие как Next.js, предлагают хранить секреты в файле .env.local и коммитить файлы .env в ваш проект. Это не рекомендуется, поскольку это может облегчить случайный коммит секретов в ваш проект. Вместо этого мы рекомендуем хранить секреты в .env, держать ваш файл .env в .gitignore и коммитить только файлы .env.example в ваш проект.

Добавление переменных среды

Для того, чтобы убедиться, что ваша сборка никогда не завершится без переменных среды, которые проект требует, вам нужно добавить новые переменные среды в двух местах:

📄 .env: Введите переменную среды, как обычно делаете в файле .env, т.е. KEY=VALUE

📄 schema.mjs: Добавьте соответствующую логику проверки для переменной среды, определив схему Zod, например KEY: z.string()

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

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

Например

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

  1. Добавье переменную среды в .env:
TWITTER_API_TOKEN=1234567890
  1. Добавьте переменную среды в schema.mjs:
export const serverSchema = z.object({
  // ...
  TWITTER_API_TOKEN: z.string(),
});

export const serverEnv = {
  // ...
  TWITTER_API_TOKEN: process.env.TWITTER_API_TOKEN,
};

Обратите внимание: Пустая строка все еще является строкой, поэтому z.string() примет пустую строку как допустимое значение. Если вы хотите убедиться, что переменная среды не пуста, вы можете использовать z.string().min(1).

  1. опционально: Добавьте переменную среды в .env.example, но не включайте токен
TWITTER_API_TOKEN=

Recent Contributors To This Page