React 안내서 · 6/6

빌드와 배포

Vite로 만든 React 앱은 빌드하면 HTML, JavaScript, CSS로 이루어진 정적 파일이 됩니다. 따라서 Node.js 서버 없이도 정적 호스팅이나 CDN, nginx 같은 웹 서버에 올려 서비스할 수 있습니다. 이 장에서는 프로덕션 빌드부터 호스팅 설정, 컨테이너 배포까지 다룹니다.

프로덕션 빌드

npm run build     # tsc -b 로 타입 검사 후 vite build
npm run preview   # dist 폴더를 http://localhost:4173 에서 미리 보기

빌드가 끝나면 dist/ 폴더가 만들어집니다. 코드는 압축되고 사용하지 않는 코드는 제거되며, dist/assets/의 파일 이름에는 내용에 따라 달라지는 해시가 붙습니다.

dist/
├── index.html
├── vite.svg
└── assets/
    ├── index-B1c2D3e4.js
    └── index-F5g6H7i8.css

npm run preview는 빌드 결과를 확인하는 용도일 뿐 실제 서비스용 서버가 아닙니다. 배포 전에는 개발 모드에서만 일어나는 StrictMode 이중 실행이 사라진 상태로 앱이 잘 동작하는지 미리 보기로 확인합니다.

환경별 설정과 하위 경로

빌드 때는 .env.production 값이 쓰이며, --mode로 다른 환경 파일을 고를 수 있습니다. 앱을 도메인 루트가 아닌 하위 경로(예: GitHub Pages의 https://사용자.github.io/저장소/)에 올린다면 base를 지정해야 자원 경로가 올바르게 만들어집니다.

# .env.staging 을 읽어 빌드
npx vite build --mode staging

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  base: "/my-app/",
});

VITE_로 시작하는 환경 변수는 빌드 결과물에 문자열로 들어가 누구나 볼 수 있습니다. 비밀 키는 프런트엔드에 두지 말고 백엔드나 서버리스 함수에서 다룹니다.

SPA 라우팅과 대체 경로

React Router 같은 클라이언트 라우터를 쓰면 /users/42 같은 주소를 브라우저에서 바로 열거나 새로 고칠 때 서버가 그 경로의 파일을 찾지 못해 404를 돌려줍니다. 정적 파일이 없는 모든 경로에 index.html을 돌려주도록 호스팅을 설정해야 합니다.

Netlify에서는 public/_redirects 파일을 두면 빌드 결과에 그대로 복사됩니다.

/*    /index.html   200

Vercel에서는 프로젝트 루트의 vercel.json에 다시 쓰기 규칙을 적습니다.

{
  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}

nginx에서는 try_files로 같은 효과를 냅니다. 해시가 붙은 assets/ 파일은 내용이 바뀌면 이름도 바뀌므로 길게 캐시하고, index.html은 캐시하지 않아 새 배포가 바로 반영되게 합니다.

server {
  listen 80;
  root /usr/share/nginx/html;
  index index.html;

  location / {
    try_files $uri $uri/ /index.html;
    add_header Cache-Control "no-cache";
  }

  location /assets/ {
    add_header Cache-Control "public, max-age=31536000, immutable";
  }
}

Docker로 배포하기

다단계 빌드를 쓰면 Node.js로 빌드한 결과물만 가벼운 nginx 이미지에 담을 수 있습니다. 위 nginx 설정을 nginx.conf로 저장해 함께 복사합니다.

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

FROM nginx:alpine
COPY nginx.conf /etc/nginx/conf.d/default.conf
COPY --from=build /app/dist /usr/share/nginx/html
EXPOSE 80

docker build -t my-app .
docker run --rm -p 8080:80 my-app

.dockerignore에 node_modules와 dist를 넣어 두면 빌드 문맥이 작아지고 빌드가 빨라집니다.

배포 전 점검

npm run lint와 테스트(npx vitest run, npx playwright test)를 CI에서 통과시킵니다.
npm run preview로 하위 경로, 새로 고침, 이미지 경로를 확인합니다.
번들 크기가 크면 React.lazy와 동적 import()로 화면 단위 코드 분할을 적용합니다.
서버 렌더링이나 SEO가 중요해지면 Next.js 같은 프레임워크로 옮기는 것을 검토합니다.

정리

npm run build는 dist/에 정적 파일을 만들고, npm run preview로 미리 봅니다.
하위 경로 배포에는 base를, 클라이언트 라우팅에는 index.html 대체 경로를 설정합니다.
해시가 붙은 자원은 길게, index.html은 짧게 캐시합니다.
Docker 다단계 빌드로 nginx 이미지에 담아 어디서나 같은 방식으로 배포할 수 있습니다.

공식 문서

이 장에 대해 질문이 있나요?