Переменные окружения: модули $env

Переменные окружения — настройки, которые задаются вне кода: адрес базы данных, ключ платёжного сервиса, название сайта. Секреты нельзя хранить в коде и в git, а на сервере значения часто отличаются от ваших локальных. SvelteKit читает такие переменные через специальные модули $env.

Файл .env

Для разработки переменные записывают в файл .env в корне проекта, рядом с package.json:

# .env
DATABASE_URL=postgres://localhost:5432/blog
API_KEY=secret-123
PUBLIC_SITE_NAME=Мой блог

Файл .env уже внесён в .gitignore проекта, созданного через sv, и не попадёт в репозиторий. После изменения .env перезапустите npm run dev.

Секреты: $env/static/private

// src/lib/server/db.js
import { DATABASE_URL, API_KEY } from '$env/static/private';
 
export function connectionInfo() {
  return `Подключаемся к ${DATABASE_URL}, ключ длиной ${API_KEY.length}`;
}

Модуль $env/static/private можно импортировать только в серверном коде: +page.server.js, +server.js, hooks.server.js, src/lib/server. Если подключить его в компоненте, сборка остановится с ошибкой — секрет не уйдёт в браузер.

Публичные значения: $env/static/public

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

<!-- src/routes/+layout.svelte -->
<script>
  import { PUBLIC_SITE_NAME } from '$env/static/public';
 
  let { children } = $props();
</script>
 
<header>{PUBLIC_SITE_NAME}</header>
{@render children()}

В шапке каждой страницы появится «Мой блог». Публичные переменные видны любому посетителю в коде страницы — не кладите в них ничего секретного.

Статические и динамические

Статические значения подставляются в код во время npm run build. Если значения задаются уже на сервере при запуске — например, один и тот же собранный проект работает с разными базами, — берите динамический модуль:

// src/hooks.server.js
import { env } from '$env/dynamic/private';
 
export async function handle({ event, resolve }) {
  event.locals.maintenance = env.MAINTENANCE === 'on';
  return resolve(event);
}

В динамических модулях переменные лежат в объекте env и читаются как его свойства.

Частая ошибка

Читать переменные через process.env.API_KEY. В режиме разработки Vite не загружает .env в process.env, и значение окажется undefined; в браузере process вообще нет. В проекте SvelteKit всегда используйте модули $env.