환경 변수 사용

astro:env를 찾고 계신가요?

타입 안정성을 갖춘 환경 변수를 위한 실험적 astro:env API에 대해 자세히 알아보세요!

Astro는 빌드 시 정적으로 교체되는 Vite에 내장된 환경 변수 지원을 사용합니다. 이를 통해 Vite가 제공하는 모든 방법을 사용하여 환경 변수를 관리할 수 있습니다.

모든 환경 변수는 서버 측 코드에서만 사용할 수 있으며, 보안을 위해 오직 PUBLIC_ 접두사를 사용하는 환경 변수만이 클라이언트 측 코드에서 사용될 수 있습니다.

.env

SECRET_PASSWORD=password123
PUBLIC_ANYBODY=there

이 예에서 PUBLIC_ANYBODY(import.meta.env.PUBLIC_ANYBODY를 통해 사용 가능)는 서버 측 코드와 클라이언트 측 코드에서 모두 사용할 수 있는 반면, SECRET_PASSWORD(import.meta.env.SECRET_PASSWORD를 통해 사용 가능)는 서버 측 코드에서만 사용할 수 있습니다.

주의

.env 파일은 구성 파일에서 불러올 수 없습니다.

기본 환경 변수

섹션 제목: 기본 환경 변수

Astro는 기본적으로 몇 가지 환경 변수를 포함하고 있습니다.

• import.meta.env.MODE: 사이트가 실행 중인 모드입니다. astro dev 명령을 실행할 때는 development이고 astro build 명령을 실행할 때는 production입니다.
• import.meta.env.PROD: 사이트가 프로덕션 환경에서 실행 중인 경우 true입니다. 그렇지 않으면 false입니다.
• import.meta.env.DEV: 사이트가 개발 환경에서 실행 중인 경우 true입니다. 그렇지 않으면 false입니다. 항상 import.meta.env.PROD와 반대입니다.
• import.meta.env.BASE_URL: 사이트의 기본 URL입니다. 이는 base 구성 옵션에 의해 결정됩니다.
• import.meta.env.SITE: 프로젝트의 astro.config 파일에 설정된 site 옵션의 값입니다.
• import.meta.env.ASSETS_PREFIX: build.assetsPrefix 구성 옵션이 설정된 경우 Astro에서 생성된 자산 링크의 접두사입니다. 이는 Astro가 처리하지 않는 자산 링크를 생성하는 데 사용될 수 있습니다.

다른 환경 변수처럼 사용하세요.

const isProd = import.meta.env.PROD;
const isDev = import.meta.env.DEV;

환경 변수 설정

섹션 제목: 환경 변수 설정

.env 파일

섹션 제목: .env 파일

환경 변수는 프로젝트 디렉터리의 .env 파일에서 불러올 수 있습니다.

.env.production 또는 .env.development처럼 파일 이름에 모드(production 또는 development)를 추가할 수도 있습니다. 이렇게 하면 환경 변수가 해당 모드에서만 적용됩니다.

프로젝트 디렉터리에 .env 파일을 생성하고 몇 가지 변수를 추가하세요.

.env

# 서버에서 실행될 때만 사용할 수 있습니다!
DB_PASSWORD="foobar"
# 어디서나 사용할 수 있습니다!
PUBLIC_POKEAPI="https://pokeapi.co/api/v2"

.env 파일에 대한 자세한 내용은 Vite 문서를 참조하세요.

CLI 사용

섹션 제목: CLI 사용

프로젝트를 실행할 때 환경 변수를 추가할 수도 있습니다.

npm

PUBLIC_POKEAPI=https://pokeapi.co/api/v2 npm run dev

pnpm

PUBLIC_POKEAPI=https://pokeapi.co/api/v2 pnpm run dev

Yarn

PUBLIC_POKEAPI=https://pokeapi.co/api/v2 yarn run dev

주의

이 방법으로 설정된 변수는 클라이언트를 포함하여 프로젝트의 모든 곳에서 사용할 수 있습니다.

환경 변수 가져오기

섹션 제목: 환경 변수 가져오기

Astro의 환경 변수는 process.env 대신 ES2020에 추가된 import.meta 기능의 import.meta.env를 통해 사용할 수 있습니다.

예를 들어 import.meta.env.PUBLIC_POKEAPI를 사용하여 PUBLIC_POKEAPI 환경 변수를 가져올 수 있습니다.

// import.meta.env.SSR === true인 경우 사용됨
const data = await db(import.meta.env.DB_PASSWORD);

// import.meta.env.SSR === false인 경우 사용됨
const data = fetch(`${import.meta.env.PUBLIC_POKEAPI}/pokemon/squirtle`);

SSR을 사용하는 경우, 사용 중인 SSR 어댑터를 통해 런타임 시 환경 변수를 사용할 수 있습니다. 대부분의 어댑터는 process.env를 통해 환경 변수를 사용하지만 일부 어댑터는 다르게 동작합니다. Deno 어댑터의 경우 Deno.env.get() 함수를 사용합니다. Cloudflare 런타임 사용에서 Cloudflare 어댑터가 환경 변수를 처리하는 방법을 알아보세요. Astro는 먼저 서버 환경에서 변수를 확인하고 변수가 존재하지 않으면 .env 파일에서 해당 변수를 찾습니다.

TypeScript 자동 완성

섹션 제목: TypeScript 자동 완성

기본적으로 Astro는 astro/client.d.ts 파일에서 import.meta.env에 대한 타입 정의를 제공합니다.

.env.[mode] 파일에서 더 많은 사용자 정의 환경 변수를 정의할 수도 있지만, PUBLIC_ 접두사를 사용하여 사용자 정의 환경 변수를 위한 TypeScript 자동 완성을 얻고 싶을 수도 있습니다.

이를 위해 src/ 디렉터리에 env.d.ts 파일을 생성하고 다음과 같이 ImportMetaEnv 인터페이스를 구성할 수 있습니다.

src/env.d.ts

interface ImportMetaEnv {
  readonly DB_PASSWORD: string;
  readonly PUBLIC_POKEAPI: string;
  // 더 많은 환경변수 ...
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}