React 배포하기

React 앱 Nginx로 배포하기

개요

React 앱은 빌드 후 생성되는 정적 파일(HTML, CSS, JS)을 Nginx가 직접 서빙하는 방식으로 배포한다.

React로 만든 프론트엔드 앱을 실제 서비스로 올리려면, npm start로 개발 서버를 돌리는 게 아니라 빌드(Build)한 결과물을 Nginx로 서빙해야 해요.

React의 npm run build 명령을 실행하면 build/ 폴더에 최적화된 정적 파일들이 생겨요. 이 파일들을 Nginx의 웹 루트에 올려놓으면 끝! Nginx가 HTML, CSS, JS 파일을 그대로 전달해주는 정적 파일 서버 역할을 하는 거예요.

배포 아키텍처

graph LR
    A[👤 사용자<br/>브라우저] -->|"<https://example.com>"| B[🖥️ Nginx<br/>포트 443/80]
    B -->|정적 파일 서빙| C["📁 /var/www/frontend/<br/>build 결과물<br/>index.html, JS, CSS"]

    style B fill:#90EE90
    style C fill:#87CEEB
Mermaid
복사

flowchart TD
    A["💻 로컬 개발"] -->|npm run build| B["📦 build/ 폴더 생성"]
    B -->|"scp 또는 CI/CD"| C["🖥️ 서버에 업로드<br/>/var/www/frontend/"]
    C --> D["⚙️ Nginx 설정<br/>정적 파일 서빙"]
    D --> E["🌐 서비스 오픈!"]

    style B fill:#FFD700
    style D fill:#90EE90
Mermaid
복사

Step 1: React 앱 빌드

# 로컬 (개발 환경)에서 빌드
cd my-react-app
npm run build

# build/ 폴더 내용 확인
ls build/
# index.html  static/  asset-manifest.json  ...
Bash
복사

build/ 폴더에 만들어지는 파일:

파일/폴더	설명
index.html	진입점 HTML
static/js/	번들링된 JavaScript
static/css/	번들링된 CSS
static/media/	이미지, 폰트 등
asset-manifest.json	에셋 매핑 정보

Step 2: 서버에 파일 업로드

# SCP로 빌드 파일 업로드
scp -r build/* ubuntu@서버IP:/var/www/frontend/

# 또는 rsync (더 효율적 — 변경된 파일만 전송)
rsync -avz --delete build/ ubuntu@서버IP:/var/www/frontend/
Bash
복사

# 서버에서 디렉토리 생성 및 권한 설정
sudo mkdir -p /var/www/frontend
sudo chown -R www-data:www-data /var/www/frontend
Bash
복사

Step 3: Nginx 설정

sudo nano /etc/nginx/sites-available/react-app
Bash
복사

server {
    listen 80;
    server_name example.com www.example.com;

    root /var/www/frontend;
    index index.html;

    # ⭐ React Router 대응 (SPA 핵심 설정!)
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 정적 에셋 캐싱 (JS, CSS 등)
    location /static/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # 파비콘 404 방지
    location = /favicon.ico {
        log_not_found off;
        access_log off;
    }

    # robots.txt
    location = /robots.txt {
        log_not_found off;
        access_log off;
    }

    # gzip 압축
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml;
    gzip_min_length 256;
}
Plain Text
복사

try_files $uri $uri/ /index.html 이 뭐야?

이 설정이 React 배포에서 가장 중요한 한 줄이에요!

flowchart TD
    A["사용자가 /about 요청"] --> B{"파일 있음?<br/>/var/www/frontend/about"}
    B -->|"있음 ($uri)"| C["해당 파일 반환"]
    B -->|"없음"| D{"폴더 있음?<br/>/var/www/frontend/about/"}
    D -->|"있음 ($uri/)"| E["폴더의 index 반환"]
    D -->|"없음"| F["🔄 /index.html 반환<br/>React Router가 처리!"]

    style F fill:#90EE90
Mermaid
복사

React는 SPA(Single Page Application)이라서, /about, /users/123 같은 경로가 실제 파일로 존재하지 않아요. 모든 라우팅은 JavaScript(React Router)가 처리하거든요.

그래서 파일이 없을 때 404를 반환하는 대신, index.html을 반환해서 React Router가 처리하도록 하는 거예요!

Step 4: 사이트 활성화

# 심볼릭 링크로 활성화
sudo ln -s /etc/nginx/sites-available/react-app /etc/nginx/sites-enabled/

# 기본 사이트 비활성화 (충돌 방지)
sudo rm /etc/nginx/sites-enabled/default

# 설정 테스트
sudo nginx -t

# 적용
sudo systemctl reload nginx
Bash
복사

Step 5: HTTPS 적용

# Certbot으로 SSL 자동 설정
sudo certbot --nginx -d example.com -d www.example.com
Bash
복사

HTTPS 적용 후 최종 설정:

server {
    listen 443 ssl http2;
    server_name example.com www.example.com;

    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    root /var/www/frontend;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /static/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml;
}

# HTTP → HTTPS 리다이렉트
server {
    listen 80;
    server_name example.com www.example.com;
    return 301 https://$host$request_uri;
}
Plain Text
복사

자주 발생하는 문제

문제	원인	해결
새로고침하면 404	try_files 미설정	try_files $uri $uri/ /index.html 추가
흰 화면 (빈 페이지)	homepage 경로 불일치	package.json의 homepage 확인
CSS/JS 로딩 안 됨	root 경로 오류	root 디렉토리 경로 확인
403 Forbidden	파일 권한 문제	chown -R www-data:www-data /var/www/frontend
캐시된 옛날 버전 표시	브라우저 캐시	강력 새로고침 (Ctrl+Shift+R)

실습

실습 환경

항목	값
로컬 프로젝트	Vite 기반 React 앱
빌드 결과 폴더	dist/
서버	alohaserver4.cafe24.com
배포 경로	/var/www/krules/frontend
SSH 접속	Host alias alohaserver4 사용

Vite는 빌드 결과가 build/ 가 아니라 dist/ 폴더에 생성돼요. CRA(Create React App)과 다른 점이에요!

SSH Config 설정 (~/.ssh/config)

터미널에서 매번 긴 주소를 치는 대신 별명(alias)으로 접속할 수 있어요.

# ~/.ssh/config

Host alohaserver4
  HostName alohaserver4.cafe24.com
  User root
Plain Text
복사

설정 후 이렇게 짧게 접속:

ssh alohaserver4        # root@alohaserver4.cafe24.com 과 동일
Bash
복사

1단계: 수동 배포 (SSH + SCP)

flowchart LR
    A["💻 로컬\\nnpm run build"] -->|"dist/ 생성"| B["📦 dist/ 폴더"]
    B -->|"scp 업로드"| C["🖥️ 서버\\n/var/www/krules/frontend/"]
    C --> D["🌐 브라우저 확인"]
Mermaid
복사

# 1. 로컬에서 빌드 (Vite → dist/)
npm run build

# 2. 서버의 배포 경로 생성 (최초 1회)
ssh root@alohaserver4.cafe24.com "mkdir -p /var/www/krules/frontend"

# 3. dist/ 내용 서버로 업로드
#    (dist/* 로 dist 폴더 자체가 아닌 내용물만 복사)
scp -r dist/* root@alohaserver4.cafe24.com:/var/www/krules/frontend/

# 4. 서버에서 파일 확인
ssh root@alohaserver4.cafe24.com "ls -la /var/www/krules/frontend/"
Bash
복사

2단계: Nginx 설정 (서버에서)

# 서버 접속
ssh root@alohaserver4.cafe24.com 

# 설정 파일 작성 - 방법1 (conf.d)
nano /etc/nginx/conf.d/krules.conf

# 설정 파일 작성 - 방법2 (sites-available)
nano /etc/nginx/sites-available/krules.conf
# sites-available → sites-enabled 심볼릭 링크
sudo ln -s /etc/nginx/sites-available/krules.conf /etc/nginx/sites-enabled/
Bash
복사

server {
    listen 80;
    server_name xn--3e0b91t.com www.xn--3e0b91t.com;

    root /var/www/krules/frontend;
    index index.html;

    # SPA 라우팅 대응
    location / {
        try_files $uri $uri/ /index.html;
    }

    # Vite 빌드 에셋 캐싱 (assets/ 폴더에 hash 파일명으로 생성됨)
    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml;
}
Plain Text
복사

sudo nginx -t && systemctl reload nginx
Bash
복사

3단계: .bat 파일로 배포 자동화

매번 명령어를 입력하는 게 귀찮으니까 클릭 한 번으로 빌드 + 배포까지 자동화해요!

비밀번호 자동 입력을 위해 PuTTY의 pscp.exe 를 사용해요. 설치: https://www.putty.org/ → pscp.exe 다운로드 후 PATH에 추가하거나 bat 파일과 같은 폴더에 두세요.

또는 SSH 키 인증을 설정하면 비밀번호 없이 일반 scp 사용 가능 (더 안전, 아래 참고)

deploy.bat (프로젝트 루트에 저장)

@echo off
chcp 65001 > nul
echo.
echo =============================================
echo   React Vite Build ^& Deploy to alohaserver4
echo =============================================
echo.

:: ────────────────────────────────────────────
:: 설정값
:: ────────────────────────────────────────────
set PROJECT_DIR=%~dp0
set REMOTE_USER=root
set REMOTE_HOST=alohaserver4.cafe24.com
set REMOTE_PATH=/var/www/krules/frontend/

:: 🔐 비밀번호 입력 (안 보이게)
for /f "delims=" %%p in ('powershell -Command "$p = Read-Host ''SSH Password'' -AsSecureString; $BSTR=[System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($p); [System.Runtime.InteropServices.Marshal]::PtrToStringAuto($BSTR)"') do set REMOTE_PASS=%%p

echo.

:: ────────────────────────────────────────────
:: [1] 빌드
:: ────────────────────────────────────────────
echo [1/2] 빌드 중...
cd /d %PROJECT_DIR%
call npm run build

if errorlevel 1 (
    echo.
    echo [오류] 빌드 실패! 에러를 확인하세요.
    pause
    exit /b 1
)

echo 빌드 완료 - dist/ 폴더 생성됨
echo.

:: ────────────────────────────────────────────
:: [2] 서버 업로드
:: ────────────────────────────────────────────
echo [2/2] 서버에 업로드 중...
pscp -pw %REMOTE_PASS% -r dist\* %REMOTE_USER%@%REMOTE_HOST%:%REMOTE_PATH%

if errorlevel 1 (
    echo.
    echo [오류] 업로드 실패! 서버 연결을 확인하세요.
    pause
    exit /b 1
)

:: ────────────────────────────────────────────
:: [3] 완료
:: ────────────────────────────────────────────
echo.
echo =============================================
echo   배포 완료!
echo   http://xn--3e0b91t.com 에서 확인하세요.
echo =============================================
echo.
pause
Shell
복사

실행 방법: deploy.bat 더블클릭 → 빌드 + 업로드 자동 진행

(선택) SSH 키 인증으로 비밀번호 없이 배포

비밀번호를 파일에 저장하는 건 보안상 좋지 않아요. SSH 키를 설정하면 비밀번호 없이 더 안전하게 자동화할 수 있어요.

# Windows PowerShell 또는 CMD에서

# 1. SSH 키 생성 (이미 있으면 생략)
ssh-keygen -t ed25519 -C "deploy-key"

# 2. 공개키를 서버에 등록
ssh-copy-id alohaserver4
# 또는 직접 붙여넣기:
# type %USERPROFILE%\\.ssh\\id_ed25519.pub | ssh alohaserver4 "cat >> ~/.ssh/authorized_keys"
Bash
복사

키 등록 후 deploy.bat 에서 pscp -pw 대신 일반 scp 사용:

:: pscp 줄을 아래로 교체
scp -r dist\\* alohaserver4:%REMOTE_PATH%
Shell
복사

체크리스트

~/.ssh/config 에 alohaserver4 Host 설정 완료?

ssh alohaserver4 접속 확인?

서버에 /var/www/krules/frontend 디렉토리 생성?

npm run build → dist/ 폴더 생성 확인?

scp -r dist/* alohaserver4:/var/www/krules/frontend/ 업로드 성공?

Nginx conf.d/krules.conf 설정 완료?

try_files $uri $uri/ /index.html 포함?

nginx -t 통과 및 systemctl reload nginx 완료?

브라우저에서 접속 확인?

deploy.bat 생성 후 자동 배포 테스트?

핵심 정리

React 배포 = npm run build → 빌드 결과물을 Nginx로 정적 서빙

핵심 설정: try_files $uri $uri/ /index.html (SPA 라우팅 대응)

정적 에셋(/static/)에는 장기 캐싱 적용 → 성능 향상

gzip 압축으로 전송 크기 절약

Certbot으로 HTTPS 적용 필수