SvelteKit 환경변수 — 안전하게 설정 관리하기

process.env 대신 $env — SvelteKit은 환경변수의 안전한 사용을 타입 시스템으로 보장합니다.

개념 정의

SvelteKit은 환경변수를 4개의 모듈로 분류하여, 비밀 키가 실수로 클라이언트에 노출되는 것을 컴파일 타임에 방지합니다.

4가지 $env 모듈

모듈	서버	클라이언트	빌드 시 인라인
`$env/static/private`	O	X	O
`$env/static/public`	O	O	O
`$env/dynamic/private`	O	X	X
`$env/dynamic/public`	O	O	X

static vs dynamic

BASH

# .env
DATABASE_URL=postgresql://localhost:5432/mydb
API_SECRET=super-secret-key
PUBLIC_API_URL=https://api.example.com
PUBLIC_APP_NAME=내 블로그

JAVASCRIPT

// static — 빌드 시 값이 코드에 인라인됩니다
import { DATABASE_URL, API_SECRET } from '$env/static/private';
import { PUBLIC_API_URL } from '$env/static/public';

// dynamic — 런타임에 값을 읽습니다 (배포 환경에서 변경 가능)
import { env } from '$env/dynamic/private';
const dbUrl = env.DATABASE_URL;

static 사용 기준: 빌드 후 변경되지 않는 값 (대부분의 경우) dynamic 사용 기준: 같은 빌드를 다른 환경에 배포할 때

private vs public

JAVASCRIPT

// private — 서버 코드에서만 import 가능
// +page.server.js, +server.js, hooks.server.js에서 사용
import { DATABASE_URL } from '$env/static/private';

// 클라이언트 코드에서 import하면 컴파일 에러!
// +page.svelte에서 import 시도 → 에러 발생

JAVASCRIPT

// public — PUBLIC_ 접두사가 붙은 변수만 공개
// 서버와 클라이언트 모두에서 사용 가능
import { PUBLIC_API_URL, PUBLIC_APP_NAME } from '$env/static/public';

.env 파일 우선순위

PLAINTEXT

.env                # 기본
.env.local          # 로컬 (gitignore)
.env.development    # 개발 환경
.env.production     # 프로덕션 환경

실전 패턴

JAVASCRIPT

// src/routes/api/posts/+server.js
import { DATABASE_URL } from '$env/static/private';
import { PUBLIC_API_URL } from '$env/static/public';
import { json } from '@sveltejs/kit';

export async function GET() {
  // 서버에서만 DB에 접근
  const posts = await fetchFromDB(DATABASE_URL);
  return json(posts);
}

SVELTE

<!-- +page.svelte — 클라이언트에서 PUBLIC_ 변수 사용 -->
<script>
  import { PUBLIC_APP_NAME } from '$env/static/public';
</script>

<h1>{PUBLIC_APP_NAME}</h1>

타입 안전

TYPESCRIPT

// src/app.d.ts에서 자동 생성된 타입 사용
// SvelteKit이 .env 파일을 기반으로 타입을 자동 생성합니다

면접 포인트

"PUBLIC_ 접두사가 왜 필요한가요?": 개발자가 의도적으로 "이 변수는 클라이언트에 노출해도 안전하다"고 선언하는 것입니다. 실수로 비밀 키를 클라이언트 코드에서 사용하면 빌드 에러가 발생합니다.
"static과 dynamic의 성능 차이는?": static은 빌드 시 값이 코드에 인라인되어 런타임 오버헤드가 없습니다. dynamic은 매 요청마다 환경변수를 읽으므로 약간의 오버헤드가 있지만, 배포 후 값을 변경할 수 있습니다.

정리

SvelteKit의 $env 시스템은 "비밀 키는 서버에만, 공개 값은 명시적으로"라는 원칙을 컴파일러 수준에서 강제합니다. process.env를 직접 쓰는 것보다 안전하고, 타입 지원으로 오타 실수도 방지할 수 있습니다.