실험적 비공개 메타 환경 변수 인라이닝

타입: boolean
기본값: false

추가된 버전: astro@5.13.0 새로운 기능

Astro 6.0 미리보기

이 기능으로 활성화된 동작은 Astro 6.0의 기본 동작이 됩니다.

원할 때마다 이 플래그를 추가할 수 있습니다. 그러면 더 빨리 이점을 누릴 수 있고, 다음 주요 Astro 버전에 맞게 프로젝트 코드를 업데이트하지 않아도 됩니다.

Astro에서는 환경 변수에 대해 타입 안전 스키마를 구성할 수 있으며, astro:env를 통해 가져온 변수를 예상되는 타입으로 변환합니다. 이렇게 하면 변수가 공개인지 비공개인지, 클라이언트에서 사용할 수 있는지 빌드 시점에 서버에서만 사용할 수 있는지, 값의 데이터 타입이 무엇인지 쉽게 확인하고 관리할 수 있으므로 Astro에서 환경 변수를 사용하는 데 권장되는 방식입니다.

그러나 필요한 경우 process.env와 import.meta.env를 통해 환경 변수에 직접 액세스할 수 있습니다. 이는 Astro 5.0에서 astro:env가 추가되기 전에 Astro에서 환경 변수를 사용할 수 있는 유일한 방법이었으며, import.meta.env를 사용할 때는 더 이상 필요하지 않은 이전 버전의 Astro를 위한 일부 로직이 포함되어 있습니다.

experimental.staticImportMetaEnv 플래그는 Vite의 환경 변수 처리에 맞게 import.meta.env에 직접 액세스할 때의 동작을 업데이트하고, import.meta.env 값이 항상 인라인으로 표시되도록 합니다.

현재 공개되지 않은 환경 변수는 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 호출로 바뀌지도 않습니다. 이렇게 하면 Astro에서 import.meta.env의 동작이 Vite와 일치하게 됩니다.

향후 주요 버전의 Astro에서는 이 동작이 기본 동작으로 전환되지만, experimental.staticImportMetaEnv 플래그를 사용하여 향후 동작을 미리 선택할 수 있습니다. 그리고 필요하다면, 이에 따라 프로젝트를 업데이트합니다.

프로젝트 업데이트

강제 변환에 의존하는 경우 프로젝트 코드를 업데이트하여 수동으로 적용해야 할 수도 있습니다.

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를 사용하는 것이 좋습니다.