Как Astro работает с переменными окружения? Что такое import.meta.env?

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

Astro использует Vite под капотом, поэтому переменные окружения работают аналогично Vite-проектам. Файлы .env, .env.local, .env.production, .env.development автоматически подгружаются в соответствии с текущим режимом.

Объект import.meta.env

Все переменные окружения доступны через import.meta.env. Astro добавляет несколько встроенных:

• import.meta.env.MODE — текущий режим: 'development' или 'production'
• import.meta.env.PROD — true в продакшне
• import.meta.env.DEV — true в разработке
• import.meta.env.BASE_URL — базовый URL приложения (из конфига base)
• import.meta.env.SITE — значение site из astro.config.mjs

Серверные и клиентские переменные

Переменные без префикса доступны только на сервере (frontmatter, SSR, эндпоинты). Переменные с префиксом PUBLIC_ встраиваются в клиентский бандл и доступны везде.

# .env
DATABASE_URL=postgresql://user:pass@localhost/db   # только сервер
PUBLIC_API_URL=https://api.example.com             # сервер + клиент
PUBLIC_ANALYTICS_ID=UA-12345678                    # сервер + клиент

Использование во frontmatter

---
// src/pages/index.astro
const dbUrl = import.meta.env.DATABASE_URL;       // OK — только сервер
const apiUrl = import.meta.env.PUBLIC_API_URL;    // OK — доступно везде

const data = await fetch(`${apiUrl}/posts`).then(r => r.json());
---

<p>API: {apiUrl}</p>

Использование в клиентском скрипте

---
// frontmatter (сервер)
---

<script>
  // Этот код выполняется в браузере
  const apiUrl = import.meta.env.PUBLIC_API_URL; // OK
  // import.meta.env.DATABASE_URL — undefined в браузере!

  const res = await fetch(`${apiUrl}/posts`);
</script>

TypeScript-типизация переменных

Добавьте типы в src/env.d.ts:

/// <reference types="astro/client" />

interface ImportMetaEnv {
  readonly DATABASE_URL: string;
  readonly PUBLIC_API_URL: string;
  readonly PUBLIC_ANALYTICS_ID: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

Переменные по режимам

# .env.development
PUBLIC_API_URL=http://localhost:3001

# .env.production
PUBLIC_API_URL=https://api.example.com

Запуск в конкретном режиме: astro build --mode staging загрузит .env.staging.

Подводные камни

• Переменные без префикса PUBLIC_ в клиентских скриптах (<script>) будут undefined — не надеяться на них в браузере.
• .env.local игнорируется в CI-средах по умолчанию — добавляйте переменные напрямую в CI-конфиг (GitHub Secrets, Vercel env vars).
• Переменные встраиваются в бандл на этапе сборки статически — изменение PUBLIC_-переменной требует пересборки.
• Не помещайте реальные секреты (API-ключи, пароли) в PUBLIC_-переменные — они видны в исходном коде браузера.
• Порядок загрузки: .env.{mode}.local > .env.local > .env.{mode} > .env — более специфичные файлы перезаписывают общие.
• В Node.js-адаптере переменные из process.env доступны отдельно от import.meta.env — убедитесь, что не смешиваете их.

• Дать секрету префикс PUBLIC_ и слить его в клиент.
• Полагаться на process.env в edge-рантайме.
• Хранить продакшен .env в репозитории.

• Знает правило про префикс PUBLIC_.
• Помнит про astro:env и его секции client/server.
• Понимает специфику Cloudflare runtime.