Экспериментальное встраивание приватных мета-переменных окружения

Тип: boolean
По умолчанию: false

Добавлено в: astro@5.13.0

Astro 6.0 превью

Поведение, включаемое этой функцией, станет поведением по умолчанию в Astro 6.0.

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

Astro позволяет настроить типобезопасную схему для ваших переменных окружения и преобразует переменные, импортированные через astro:env, в ожидаемый тип. Это рекомендуемый способ использования переменных окружения в Astro, так как он позволяет легко видеть и управлять тем, являются ли ваши переменные общедоступными или секретными, доступны ли они на клиенте или только на сервере во время сборки, а также типом данных ваших значений.

Однако вы все равно можете получить доступ к переменным окружения через process.env, а также import.meta.env напрямую, если это необходимо. Это был единственный способ использования переменных окружения в Astro до того, как astro:env был добавлен в Astro 5.0, и его обработка import.meta.env включает некоторую логику, которая предназначалась для более ранних версий Astro, которая больше не нужна.

Флаг experimental.staticImportMetaEnv обновляет поведение при прямом доступе к import.meta.env, чтобы оно соответствовало обработке переменных окружения Vite и гарантирует, что значения import.meta.env всегда встраиваются (inlined).

В настоящее время непубличные переменные окружения заменяются ссылкой на process.env. Кроме того, Astro также может преобразовывать тип значения ваших переменных окружения, используемых через import.meta.env, что может препятствовать доступу к некоторым значениям, таким как строки "true" (которая преобразуется в логическое значение) и "1" (которая преобразуется в число).

Флаг experimental.staticImportMetaEnv упрощает поведение Astro по умолчанию, делая его более понятным и простым в использовании. Astro больше не будет заменять никакие переменные окружения import.meta.env вызовом process.env, а также не будет принудительно преобразовывать значения.

Чтобы включить эту функцию, добавьте экспериментальный флаг в вашу конфигурацию Astro:

astro.config.mjs

import { defineConfig } from "astro/config"

export default defineConfig({
  experimental: {
    staticImportMetaEnv: true,
  }
})

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

Включение этого экспериментального флага больше не будет преобразовывать строковые значения в логические или числовые, а также превращать значения import.meta.env в вызовы process.env. Это выравнивает поведение import.meta.env в Astro с Vite.

В будущей основной версии Astro переключится на это поведение по умолчанию, но вы можете включить будущее поведение раньше, используя флаг experimental.staticImportMetaEnv и, при необходимости, обновив ваш проект соответствующим образом.

Обновление вашего проекта

Если вы полагались на принудительное преобразование типов (coercion), вам может потребоваться обновить код вашего проекта, чтобы применить его вручную:

src/components/MyComponent.astro

const enabled: boolean = import.meta.env.ENABLED;
const enabled: boolean = import.meta.env.ENABLED === "true";

Если вы полагались на преобразование в process.env, вам может потребоваться обновить код вашего проекта, чтобы применить его вручную:

src/components/MyComponent.astro

const enabled: boolean = import.meta.env.DB_PASSWORD;
const enabled: boolean = process.env.DB_PASSWORD;

Вам также может потребоваться обновить типы:

src/env.d.ts

interface ImportMetaEnv {
  readonly PUBLIC_POKEAPI: string;
  readonly DB_PASSWORD: string;
  readonly ENABLED: boolean;
  readonly ENABLED: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

namespace NodeJS {
  interface ProcessEnv {
    DB_PASSWORD: string;
  }
}

Если вам нужен больший контроль над переменными окружения в Astro, мы рекомендуем использовать astro:env.