빌드와 배포

SvelteKit 앱은 vite build로 빌드하고, 어댑터가 그 결과를 배포할 환경에 맞는 형태로 바꿉니다. 같은 코드라도 어댑터만 바꾸면 Node.js 서버, 정적 사이트, 서버리스 플랫폼에 배포할 수 있습니다.

빌드와 미리 보기

npm run build     # vite build: 앱을 빌드하고 어댑터를 실행
npm run preview   # 빌드 결과를 로컬에서 확인(기본 주소 http://localhost:4173)

npm run preview는 Vite의 미리 보기 서버로 결과를 확인하는 용도이며, 운영 서버로 쓰지 않습니다. 실제 실행 방식은 어댑터가 결정합니다.

어댑터 고르기

어댑터는 vite.config.ts의 sveltekit() 옵션으로 지정합니다. 새 프로젝트의 기본값인 adapter-auto는 빌드 환경을 보고 알맞은 어댑터를 고르지만, 배포 대상이 정해졌다면 해당 어댑터를 직접 설치해 지정하는 것이 좋습니다.

이 밖에도 커뮤니티가 만든 어댑터가 여러 플랫폼용으로 있습니다.

Node.js 서버로 배포

npm install -D @sveltejs/adapter-node

// vite.config.ts
import adapter from '@sveltejs/adapter-node';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    sveltekit({
      adapter: adapter(),
      paths: { origin: 'https://example.com' }
    })
  ]
});

npm run build를 실행하면 build 폴더에 서버가 만들어지고 node build로 실행합니다. 기본 주소는 0.0.0.0:3000이며 PORT와 HOST 환경 변수로 바꿉니다. paths.origin은 앱의 공개 주소로, CSRF 검사와 프리렌더링에 쓰입니다. devDependencies의 패키지는 빌드 결과에 함께 묶이고 dependencies의 패키지는 실행할 때 node_modules에서 읽으므로, 운영 서버에는 build 폴더, package.json, 운영용 의존성이 있어야 합니다. 운영에서는 .env 파일을 자동으로 읽지 않으므로 필요하면 node --env-file=.env build처럼 실행합니다.

Docker로 묶기

FROM node:lts-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build && npm prune --omit=dev

FROM node:lts-alpine
WORKDIR /app
COPY --from=build /app/build ./build
COPY --from=build /app/node_modules ./node_modules
COPY package.json .
ENV NODE_ENV=production
EXPOSE 3000
CMD ["node", "build"]

정적 사이트로 배포

서버 없이 파일만 올리는 호스팅(GitHub Pages, 일반 웹 서버, CDN)에는 adapter-static을 씁니다. 모든 페이지를 빌드 때 HTML로 만들어야 하므로 루트 레이아웃에 prerender를 켭니다.

// vite.config.ts 의 sveltekit() 옵션
import adapter from '@sveltejs/adapter-static';

sveltekit({
  adapter: adapter({
    pages: 'build',
    assets: 'build',
    fallback: undefined,
    precompress: false,
    strict: true
  })
});

// src/routes/+layout.ts
// export const prerender = true;

이 방식에서는 폼 액션과 서버 load처럼 요청마다 서버가 필요한 기능을 쓸 수 없습니다. 프리렌더링이 어려운 앱을 SPA로 배포하려면 fallback: '200.html'을 지정할 수 있지만, 성능과 검색 노출에 불리하므로 꼭 필요한 경우에만 씁니다.

배포 전 확인할 것

• npm run check와 테스트가 통과하는지 확인합니다.
• 비밀 값은 $app/env/private로만 쓰고, 운영 환경 변수로 넘깁니다.
• 프록시 뒤에서 Node 서버를 운영한다면 adapter-node 문서의 프록시 헤더 설정을 확인합니다.
• 배포 대상이 정해지면 adapter-auto 대신 해당 어댑터를 직접 지정합니다.

정리

• npm run build가 앱을 빌드하고 어댑터가 배포 형태를 만듭니다.
• Node 서버는 adapter-node와 node build, 정적 호스팅은 adapter-static과 프리렌더링을 씁니다.
• Vercel, Netlify, Cloudflare 같은 플랫폼에는 전용 어댑터가 있습니다.

더 자세한 내용은 공식 문서를 참고하세요.

• SvelteKit 문서
• Building your app
• Adapters
• Node servers
• Static site generation