환경 변수 사용하기(Using Environment Variables)

Astro는 Vite의 내장 환경 변수 지원에 접근할 수 있고, 프로젝트의 기본 환경 변수도 포함해요. 이 변수들로 현재 프로젝트의 site·base 같은 설정값, 개발/프로덕션 실행 여부 등을 알 수 있어요. 더 나아가 타입 안전한 환경 변수 체계(astro:env)도 제공해요.

출처: https://docs.astro.build/en/guides/environment-variables/

Vite의 내장 지원

Astro는 환경 변수에 대한 Vite의 내장 지원(빌드 시점에 정적으로 치환됨)을 사용하며, Vite의 방법을 그대로 써서 작업할 수 있어요.

기본 환경 변수

import.meta.env.MODE — 사이트가 실행 중인 모드. astro dev에서 development, astro build에서 production.
import.meta.env.PROD — 프로덕션이면 true, 아니면 false.
import.meta.env.DEV — 개발이면 true. 항상 PROD의 반대.
import.meta.env.BASE_URL — 사이트가 서빙되는 base URL. base 설정 옵션에 의해 결정돼요.
import.meta.env.SITE — 프로젝트 astro.config의 site 옵션 값.

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

환경 변수 설정

`.env` 파일

파일 이름에 .production, .development 또는 커스텀 모드 이름을 붙일 수 있어요(예: .env.testing, .env.staging). 이렇게 하면 다른 시점에 서로 다른 환경 변수 세트를 쓸 수 있어요.

환경 변수 가져오기

환경 변수는 import.meta.env로 접근해요. 여기서 중요한 점은 클라이언트에 노출되는 변수는 PUBLIC_ 접두사를 써야 한다는 거예요. 서버 전용 변수(시크릿)는 import.meta.env.SSR이 true인 서버 코드에서만 접근해야 해요.

Cloudflare 어댑터를 쓸 때는 Cloudflare 런타임을 통한 환경 변수 처리도 참고하세요. Astro는 먼저 서버 환경에서 변수를 찾고, 없으면 .env 파일에서 찾아요.

타입 안전한 환경 변수

astro:env API로 환경 변수에 대한 타입 안전한 스키마를 구성할 수 있어요. 서버나 클라이언트에서 사용 가능한지, 데이터 타입과 추가 속성을 정의할 수 있어요.

스키마에서 변수 사용

---
import { API_URL } from "astro:env/client";
import { API_SECRET_TOKEN } from "astro:env/server";

const data = await fetch(`${API_URL}/users`, {
  method: "GET",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${API_SECRET_TOKEN}`,
  },
})
---

변수 타입

context("client" 또는 "server")와 access("secret" 또는 "public") 설정의 조합에 따라 세 종류의 환경 변수가 있어요.

Public client variables — 최종 클라이언트·서버 번들 양쪽에 포함되고, astro:env/client 모듈로 양쪽에서 접근 가능.
Public server variables — 최종 서버 번들에 포함되고, astro:env/server 모듈로 서버에서 접근.
Secret server variables — 번들에 포함되지 않고, astro:env/server 모듈로 서버에서 접근.

참고: Secret client variables는 지원되지 않아요. 이 데이터를 클라이언트로 보내는 안전한 방법이 없기 때문이에요. 그래서 스키마에서 context: "client"와 access: "secret"을 동시에 구성하는 건 불가능해요.

데이터 타입

현재 문자열(string), 숫자(number), enum, 불리언(boolean) 네 가지 타입이 지원돼요. astro/config의 envField로 정의합니다.

import { envField } from "astro/config";

envField.string({
  context: "server",
  access: "public",
  optional: true,
  default: "foo",
})

제약 사항

astro:env는 가상 모듈이라 Astro 컨텍스트 안에서만 쓸 수 있어요. 미들웨어, Astro 라우트·엔드포인트, Astro 컴포넌트, 프레임워크 컴포넌트, 모듈에서는 쓸 수 있지만, 그 밖의 곳에서는 process.env를 써야 해요.

더 알아보기

환경 변수 구성(Configuration Reference): https://docs.astro.build/en/reference/configuration-reference/
배포: https://docs.astro.build/en/guides/deploy/
Vite 환경 변수와 모드: https://vite.dev/guide/env-and-mode.html

환경 변수 사용하기(Using Environment Variables)