Переменные окружения

Переменные окружения — настройки, которые различаются на вашем компьютере и на сервере: адрес API, ключи доступа, название сайта. Их хранят вне кода, в файле .env. В Astro 5 переменные описывают схемой в настройках и читают из модулей astro:env/client и astro:env/server, а Astro проверяет, что они заданы и имеют нужный тип.

Файл .env

Создайте в корне проекта, рядом с package.json, файл .env:

SITE_TITLE=Блог Анны
BOOKS_API_TOKEN=secret-123

Каждая строка — ИМЯ=значение. Файл .env уже указан в .gitignore шаблона, поэтому в репозиторий он не попадёт.

Схема переменных

Опишите переменные в astro.config.mjs:

// astro.config.mjs
import { defineConfig, envField } from 'astro/config';
 
export default defineConfig({
  env: {
    schema: {
      SITE_TITLE: envField.string({ context: 'client', access: 'public', default: 'Блог' }),
      BOOKS_API_TOKEN: envField.string({ context: 'server', access: 'secret' }),
    },
  },
});

Параметр	Значение
`context: 'client'`	Переменную можно использовать и в браузерном коде
`context: 'server'`	Только на сервере: во фронтматтере, эндпоинтах, действиях
`access: 'public'`	Значение можно вставить в собранный код
`access: 'secret'`	Секрет: никогда не попадает в браузер
`default`	Значение, если переменная не задана

Кроме envField.string есть envField.number, envField.boolean и envField.enum.

Чтение переменных

Публичную переменную читают из astro:env/client, например в макете src/layouts/BaseLayout.astro:

---
import { SITE_TITLE } from 'astro:env/client';
---
 
<title>{Astro.props.title} — {SITE_TITLE}</title>

Секрет — из astro:env/server, например при загрузке книг в src/pages/books.astro:

---
import { BOOKS_API_TOKEN } from 'astro:env/server';
 
const response = await fetch('https://example.com/api/books.json', {
  headers: { Authorization: `Bearer ${BOOKS_API_TOKEN}` },
});
---

Если BOOKS_API_TOKEN не задан, Astro остановится с ошибкой и назовёт пропущенную переменную. Секретный модуль нельзя импортировать в код для браузера — Astro выдаст ошибку сборки, и ключ не утечёт.

import.meta.env

Встроенные значения Astro читают через import.meta.env: import.meta.env.DEV — истина в режиме разработки, import.meta.env.PROD — в собранном сайте. Раньше этим способом читали и свои переменные; в Astro 5 для них удобнее astro:env.

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

После изменения .env или схемы продолжают работать со старыми значениями. Сервер разработки читает переменные при запуске — остановите его через Ctrl+C и запустите npm run dev заново. На сервере хостинга переменные задают в его настройках, а не файлом .env из репозитория.

Спасибо, что читаете!