환경 변수 사용

Astro는 Vite의 내장 환경 변수 지원에 대한 접근 권한을 제공하며, 현재 프로젝트의 구성 값 (site, base 등), 프로젝트가 개발 또는 프로덕션 환경에서 실행 중인지 여부 등에 접근할 수 있도록 몇 가지 기본 환경 변수를 포함합니다.

Astro는 타입 안정성을 갖춘 환경 변수를 사용하고 구성하는 방법도 제공합니다. Astro 컨텍스트 (예: Astro 컴포넌트, 라우트 및 엔드포인트, UI 프레임워크 컴포넌트, 미들웨어)에서 사용할 수 있으며, Astro 구성의 스키마를 통해 관리됩니다.

Vite의 내장 지원

Astro는 빌드 시 정적으로 대체되는 환경 변수에 대한 Vite의 내장 지원을 사용하며, 환경 변수를 다루기 위한 모든 메서드를 사용할 수 있습니다.

서버 측 코드에서는 모든 환경 변수를 사용할 수 있지만, 보안상의 이유로 클라이언트 측 코드에서는 PUBLIC_ 접두사가 붙은 환경 변수만 사용할 수 있습니다.

SECRET_PASSWORD=password123
PUBLIC_ANYBODY=there

이 예시에서 PUBLIC_ANYBODY (import.meta.env.PUBLIC_ANYBODY를 통해 접근 가능)는 서버 또는 클라이언트 코드에서 사용할 수 있지만, SECRET_PASSWORD (import.meta.env.SECRET_PASSWORD를 통해 접근 가능)는 서버 측에서만 사용할 수 있습니다.

:::caution.env 파일은 구성 파일에서 로드되지 않습니다.:::

TypeScript를 위한 IntelliSense

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

.env.[mode] 파일에서 더 많은 사용자 정의 환경 변수를 정의할 수 있지만, PUBLIC_ 접두사가 붙은 사용자 정의 환경 변수에 대해 TypeScript IntelliSense를 얻고 싶을 수 있습니다.

이를 위해 src/에 env.d.ts 파일을 생성하여 전역 타입을 확장하고 ImportMetaEnv를 다음과 같이 구성할 수 있습니다.

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

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

기본 환경 변수

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 옵션으로 설정됩니다.

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

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

환경 변수 설정

`.env` 파일

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

프로젝트 디렉터리에 .env 파일을 생성하고 몇 가지 변수를 추가하기만 하면 됩니다.

# 서버에서 실행될 때만 사용할 수 있습니다!
DB_PASSWORD="foobar"

# 어디서나 사용할 수 있습니다!
PUBLIC_POKEAPI="https://pokeapi.co/api/v2"

.production, .development 또는 사용자 정의 모드 이름을 파일 이름에 추가할 수도 있습니다 (예: .env.testing, .env.staging). 이를 통해 서로 다른 시간에 다른 환경 변수 집합을 사용할 수 있습니다.

astro dev 및 astro build 명령은 각각 "development" 및 "production" 모드를 기본값으로 사용합니다. --mode 플래그와 함께 이러한 명령을 실행하여 mode에 대한 다른 값을 전달하고, 일치하는 .env 파일을 로드할 수 있습니다.

이를 통해 다양한 API에 연결하여 개발 서버를 실행하거나 사이트를 빌드할 수 있습니다.

 # "스테이징" API에 연결된 개발 서버를 실행합니다.
 npm run astro dev -- --mode staging

 # 추가 디버그 정보와 함께 "프로덕션" API에 연결되는 사이트를 빌드합니다.
 npm run astro build -- --devOutput

 # "테스트" API에 연결되는 사이트를 빌드합니다.
 npm run astro build -- --mode testing

 # "스테이징" API에 연결된 개발 서버를 실행합니다.
 pnpm astro dev --mode staging

 # 추가 디버그 정보와 함께 "프로덕션" API에 연결되는 사이트를 빌드합니다.
 pnpm astro build --devOutput

 # "테스트" API에 연결되는 사이트를 빌드합니다.
 pnpm astro build --mode testing

 # "스테이징" API에 연결된 개발 서버를 실행합니다.
 yarn astro dev --mode staging

 # 추가 디버그 정보와 함께 "프로덕션" API에 연결되는 사이트를 빌드합니다.
 yarn astro build --devOutput

 # "테스트" API에 연결되는 사이트를 빌드합니다.
 yarn astro build --mode testing

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

Astro 구성 파일

Astro는 다른 파일을 로드하기 전에 구성 파일을 평가합니다. 즉, astro.config.mjs에서 .env 파일에 설정된 환경 변수에 접근하기 위해 import.meta.env를 사용할 수 없습니다.

CLI에서 설정한 것과 같은 다른 환경 변수에 접근하기 위해 구성 파일에서 process.env를 사용할 수 있습니다.

Vite의 loadEnv 도우미를 사용하여 .env 파일을 수동으로 로드할 수도 있습니다.

import { loadEnv } from "vite";

const { SECRET_PASSWORD } = loadEnv(process.env.NODE_ENV, process.cwd(), "");

:::notepnpm은 프로젝트에 직접 설치되지 않은 모듈을 가져오는 것을 허용하지 않습니다. pnpm을 사용하는 경우 loadEnv 도우미를 사용하려면 vite를 설치해야 합니다.

pnpm add -D vite

:::

CLI 사용

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

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

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

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

환경 변수 가져오기

Astro의 환경 변수는 process.env 대신 ES2020에 추가된 import.meta 기능을 사용하여 import.meta.env로 접근합니다.

예를 들어 PUBLIC_POKEAPI 환경 변수를 가져오려면 import.meta.env.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 파일에서 찾습니다.

타입 안전 환경 변수

astro:env API를 사용하면 설정한 환경 변수에 대한 타입 안전 스키마를 구성할 수 있습니다. 이를 통해 서버 또는 클라이언트에서 사용할 수 있는지 여부를 나타내고 데이터 타입 및 추가 속성을 정의할 수 있습니다.

어댑터를 개발 중이신가요? astro:env와 호환되는 어댑터를 만드는 방법을 확인하세요.

기본 사용법

스키마 정의

스키마를 구성하려면 Astro 구성에 env.schema 옵션을 추가하세요.

import { defineConfig } from "astro/config";

export default defineConfig({
  env: {
    schema: {
      // ...
    }
  }
})

그런 다음 envField 도우미를 사용하여 변수를 문자열, 숫자, enum 또는 부울로 등록할 수 있습니다. 각 변수에 대한 context ("client" 또는 "server") 및 access ("secret" 또는 "public")를 제공하여 환경 변수의 종류를 정의하고 객체에 optional 또는 default와 같은 추가 속성을 전달합니다.

import { defineConfig, envField } from "astro/config";

export default defineConfig({
  env: {
    schema: {
      API_URL: envField.string({ context: "client", access: "public", optional: true }),
      PORT: envField.number({ context: "server", access: "public", default: 4321 }),
      API_SECRET: envField.string({ context: "server", access: "secret" }),
    }
  }
})

astro dev 또는 astro build를 실행하면 타입이 생성되지만, astro sync를 실행하여 타입만 생성할 수도 있습니다.

스키마의 변수 사용

적절한 /client 또는 /server 모듈에서 정의된 변수를 가져와서 사용하세요.

---
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}`
	},
})
---

<script>
  import { API_URL } from "astro:env/client";
  
  fetch(`${API_URL}/ping`)
</script>

변수 타입

스키마에 정의된 context ("client" 또는 "server")와 access ("secret" 또는 "public") 설정의 조합에 따라 세 가지 종류의 환경 변수를 사용할 수 있습니다.

공개 클라이언트 변수: 이러한 변수는 최종 클라이언트 및 서버 번들에 모두 포함되며, astro:env/client 모듈을 통해 클라이언트와 서버 모두에서 접근할 수 있습니다.
```
import { API_URL } from "astro:env/client";
```
공개 서버 변수: 이러한 변수는 최종 서버 번들에 포함되며, astro:env/server 모듈을 통해 서버에서 접근할 수 있습니다.
```
import { PORT } from "astro:env/server";
```
비밀 서버 변수: 이러한 변수는 최종 번들의 일부가 아니며, astro:env/server 모듈을 통해 서버에서 접근할 수 있습니다.
```
import { API_SECRET } from "astro:env/server";
```
기본적으로, astro:env/server 모듈에서 무언가를 가져올 때마다 모든 비밀 변수가 검증됩니다. 이는 비밀 변수를 가져오지 않은 경우에도 검증될 수 있음을 의미합니다. 빌드 중에 이 검증을 통과하기 위해 더미 환경 변수를 전달해야 할 수도 있습니다.

validateSecrets: true를 구성하여 시작 시 비밀 변수 유효성 검사를 활성화할 수도 있습니다.

:::note비밀 클라이언트 변수는 지원되지 않습니다. 이 데이터를 클라이언트로 안전하게 전송할 방법이 없기 때문입니다. 따라서 스키마에서 context: "client"와 access: "secret"을 모두 구성하는 것은 불가능합니다.:::

데이터 타입

현재 문자열, 숫자, enum 및 부울의 네 가지 데이터 타입이 지원됩니다.

import { envField } from "astro/config";

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

envField.number({
   // context & access
   optional: true,
   default: 15,
})

envField.boolean({
   // context & access
   optional: true,
   default: true,
})

envField.enum({
   // context & access
   values: ["foo", "bar", "baz"],
   optional: true,
   default: "baz",
})

유효성 검사 필드의 전체 목록은 envField API 참조를 확인하세요.

비밀 변수를 동적으로 검색

스키마를 정의했음에도 불구하고, 특정 비밀 변수의 원시 값을 검색하거나 스키마에 정의되지 않은 비밀 변수를 검색해야 할 수 있습니다. 이 경우 astro:env/server에서 내보낸 getSecret()을 사용할 수 있습니다.

import {
   FOO, // boolean
   getSecret
} from "astro:env/server";

getSecret("FOO"); // string | undefined

API 참조에서 자세히 알아보세요.

제한 사항

astro:env는 가상 모듈이므로 Astro 컨텍스트에서만 사용할 수 있습니다. 예를 들어 다음과 같은 곳에서 사용할 수 있습니다.

미들웨어
Astro 라우트 및 엔드포인트
Astro 컴포넌트
프레임워크 컴포넌트
모듈

다음과 같은 곳에서는 사용할 수 없으므로 process.env를 사용해야 합니다.

astro.config.mjs
스크립트

기여하기 커뮤니티 후원하기

환경 변수 사용

Vite의 내장 지원

TypeScript를 위한 IntelliSense

기본 환경 변수

환경 변수 설정

.env 파일

Astro 구성 파일

CLI 사용

환경 변수 가져오기

타입 안전 환경 변수

기본 사용법

스키마 정의

스키마의 변수 사용

변수 타입

데이터 타입

비밀 변수를 동적으로 검색

제한 사항

`.env` 파일