import PackageManagerTabs from '/components/tabs/PackageManagerTabs.astro'; import ReadMore from '/components/ReadMore.astro';

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

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

Vite의 내장 지원

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

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

SECRET_PASSWORD=password123PUBLIC_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 옵션으로 설정됩니다.
• import.meta.env.ASSETS_PREFIX: build.assetsPrefix 구성 옵션이 설정된 경우 Astro에서 생성된 자산 링크의 접두사입니다. Astro에서 처리하지 않는 자산 링크를 생성하는 데 사용할 수 있습니다.

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

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에 연결하여 개발 서버를 실행하거나 사이트를 빌드할 수 있습니다.

.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(), "");

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

pnpm add -D vite

:::

CLI 사용

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

환경 변수 가져오기

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 모듈을 통해 클라이언트와 서버 모두에서 접근할 수 있습니다.

  js

  코드 복사

  코드를 클립보드에 복사

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

• 공개 서버 변수: 이러한 변수는 최종 서버 번들에 포함되며, astro:env/server 모듈을 통해 서버에서 접근할 수 있습니다.

  js

  코드 복사

  코드를 클립보드에 복사

  import { PORT } from "astro:env/server";

• 비밀 서버 변수: 이러한 변수는 최종 번들의 일부가 아니며, astro:env/server 모듈을 통해 서버에서 접근할 수 있습니다.

  js

  코드 복사

  코드를 클립보드에 복사

  import { API_SECRET } from "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
• 스크립트