[Svelte 시리즈 19편] 배포, 환경 변수, 프로덕션 체크리스트

앱이 안정적으로 돌아가려면 배포 과정이 반복 가능해야 합니다.

이번 글에서 새로 나오는 용어

1. 환경 변수: 코드 밖 .env 파일이나 서버 설정에 숨겨 두는 값으로, API 키나 DB 주소 같은 민감한 정보를 저장합니다.
2. 어댑터: SvelteKit 빌드 결과를 특정 플랫폼(Vercel, Node, Cloudflare 등)에서 실행 가능하게 변환하는 플러그인입니다.
3. CI/CD: 코드를 push하면 자동으로 테스트·빌드·배포까지 이어지는 파이프라인을 뜻합니다.
4. 롤백: 문제가 생겼을 때 이전 버전으로 되돌리는 절차로, 안정적인 배포를 위해 사전 준비가 필요합니다.

개념

환경 변수(environment variable, 환경 설정 값)는 코드 밖에서 민감한 값을 관리하는 방법입니다. .env 파일을 환경별로 분리하고 서버 전용 값은 $env/static/private나 $env/dynamic/private로 불러옵니다. 어댑터(adapter, 배포 대상 변환기)는 SvelteKit 빌드 결과를 어떤 환경에서 실행할지 결정하는 플러그인입니다. CI/CD(Continuous Integration/Continuous Delivery, 지속 통합·배포)는 코드를 자동으로 테스트하고 배포하는 파이프라인입니다.

숨은 규칙 체크

• $env/static/* 모듈은 빌드 타임에 값이 고정됩니다. 빌드 이후 값이 바뀔 예정이면 반드시 $env/dynamic/*을 써야 합니다.
• .env 파일은 기본적으로 Git에 올리지 않습니다. 샘플이 필요하면 .env.example만 커밋하세요.
• 어댑터는 한 번에 하나만 활성입니다. adapter-auto를 쓰다가 adapter-node로 바꾸려면 svelte.config.js에서 명확히 교체해야 합니다.

코드

환경 변수와 GitHub Actions 예시를 간단히 살펴봅니다.

.env                # 공통(로컬)
.env.local          # 개발자별 오버라이드
.env.production     # 배포 서버 전용

const dbUrl = PRIVATE_DB_URL;
const apiKey = env.API_KEY;

(선택) CI/CD와 롤백 자동화

시간이 넉넉할 때만 아래 흐름을 붙이세요. 동아리 프로젝트라면 수동 배포도 충분합니다.

name: deploy
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v3
      - run: pnpm install --frozen-lockfile
      - run: pnpm test
      - run: pnpm run build

웹소켓이나 SSE처럼 장시간 연결이 필요한 기능을 배포한다면 adapter-node나 adapter-vercel처럼 Node 환경 어댑터가 더 안전합니다. 정적 호스팅(Vercel Edge, Cloudflare Pages)에서는 SSE가 제한될 수 있으니, 필요할 때만 어댑터를 교체하세요.

왜 중요한가

환경 변수가 정리되지 않으면 배포마다 값이 뒤섞입니다. CI가 없으면 누가 어떤 버전을 배포했는지 추적하기 어렵습니다. 작은 동아리 프로젝트라도 자동화된 흐름을 만들어 두면 새 팀원이 합류했을 때 같은 절차를 따라갈 수 있습니다.

실습

• 따라 하기: .env 파일을 환경별로 나누고 $env/static과 $env/dynamic을 각각 사용하는 코드를 작성한다.
• 확장하기: GitHub Actions 예시를 참고해 테스트와 빌드를 실행하는 워크플로를 만든다.
• 디버깅: 배포 오류가 나면 어댑터 설정과 환경 변수 로딩 위치를 우선 확인한다.
• 완료 기준: 환경 변수 목록과 어댑터 선택 이유가 README나 노트에 정리되어 반복 가능한 배포 절차가 준비된다.

마무리

배포 단계까지 정리하면 제품을 다른 사람에게 보여 줄 수 있는 상태가 됩니다. 다음 편에서는 전체 시리즈를 캡스톤 프로젝트로 묶어 마무리합니다.