티스토리 뷰
React 프로젝트를 어느 정도 만들고 나면 그다음부터 막히는 건 코드보다 배포입니다. 로컬에서는 잘 돌아가는데, 막상 리눅스 서버에 올리려 하면 build 파일은 어디에 올려야 하는지, 정적 파일은 어떻게 서비스해야 하는지, 새로고침했을 때 404는 왜 나는지 같은 문제가 한꺼번에 생기기 때문입니다.
처음 배포를 할 때는 “그냥 build 폴더만 업로드하면 끝나는 거 아닌가?” 싶지만, 실제로는 그 뒤에 한 번 더 봐야 할 부분이 있습니다. 서버에 파일을 어디에 둘지, 웹서버가 어느 경로를 바라보게 할지, React Router를 쓰고 있다면 새로고침 이슈는 어떻게 처리할지까지 같이 맞춰야 실제 서비스처럼 보입니다.
그래서 이 글에서는 어렵게 이론부터 길게 설명하지 않고, React 프로젝트를 build하고, 리눅스 서버에 올리고, Nginx로 실제 서비스하는 흐름을 처음 하는 사람도 따라가기 쉽게 정리해보겠습니다. 중간에 자주 막히는 포인트도 같이 짚겠습니다.
많이 헷갈리는 부분부터 먼저 정리하면, React 프로젝트를 리눅스 서버에 배포할 때 Node.js로 개발 서버를 그대로 띄우는 게 핵심은 아닙니다. 보통은 npm run build로 만든 정적 파일 묶음을 서버에 올리고, 그 파일을 Nginx 같은 웹서버가 읽어서 브라우저에 내려주는 방식으로 운영합니다.
즉 배포 흐름을 아주 단순하게 보면 이렇게 이해하시면 됩니다.
React 프로젝트 개발 완료
↓
npm run build
↓
build 폴더 생성
↓
리눅스 서버 업로드
↓
Nginx가 build 파일 서비스
↓
브라우저 접속 확인
React 배포는 “React 앱을 실행한다”보다 “build된 정적 파일을 서버에서 열리게 만든다”라고 생각하면 훨씬 이해가 쉽습니다.
1. build 파일 만들기
배포 전에 먼저 로컬 또는 빌드 서버에서 React 프로젝트를 build해야 합니다.
npm install
npm run build
보통 build가 끝나면 build/ 폴더가 생성됩니다. 이 폴더 안에는 배포에 필요한 정적 파일이 들어 있습니다.
2. 리눅스 서버로 업로드하기
이제 생성된 build 폴더를 서버로 올립니다. 예를 들어 /var/www/react-app 같은 디렉터리를 만들고 그 안에 build 결과물을 복사할 수 있습니다.
scp -r build/* user@server:/var/www/react-app/
혹은 rsync를 쓰면 변경 파일만 반영하기 쉬워서 운영할 때 더 편합니다.
rsync -avz --delete build/ user@server:/var/www/react-app/
3. Nginx에서 정적 파일 서비스하기
Nginx는 React 앱 자체를 “실행”하는 것이 아니라, 업로드된 build 파일을 사용자에게 보여주는 역할을 합니다.
server {
listen 80;
server_name example.com;
root /var/www/react-app;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
}
여기서 중요한 건 try_files 설정입니다. React Router를 쓰는 프로젝트는 /about, /profile 같은 경로를 직접 새로고침하면 서버는 실제 파일을 찾으려다가 404를 낼 수 있는데, index.html로 다시 넘겨줘야 정상적으로 열립니다.
문제 1. 첫 화면은 열리는데 새로고침하면 404가 나는 경우
이건 React Router를 쓰는 프로젝트에서 정말 자주 나오는 문제입니다. 브라우저는 /users 같은 경로로 접근했는데, 서버는 그 경로에 실제 파일이 없다고 판단해 404를 내는 겁니다.
이럴 때는 Nginx에서 아래 설정이 필요합니다.
location / {
try_files $uri $uri/ /index.html;
}
문제 2. build 파일을 올렸는데 예전 화면이 계속 보이는 경우
이럴 때는 서버에 파일이 제대로 덮어써졌는지, 브라우저 캐시가 남아 있는지, Nginx가 다른 경로를 보고 있지는 않은지 같이 확인해야 합니다.
특히 root 경로가 실제 업로드 경로와 다르면 배포를 여러 번 해도 화면이 안 바뀝니다.
문제 3. API 호출만 실패하는 경우
프론트 배포는 됐는데 API만 실패한다면 보통은 React 문제가 아니라 환경변수, API 서버 주소, 프록시, CORS 쪽을 같이 봐야 합니다. 즉 화면이 떴다고 배포가 완전히 끝난 건 아니라는 뜻입니다.
- `npm run build`가 정상 완료됐는지 확인
- 서버 업로드 경로와 Nginx `root` 경로가 일치하는지 확인
- `try_files $uri $uri/ /index.html;` 설정이 들어갔는지 확인
- 정적 파일 권한이 웹서버가 읽을 수 있는 상태인지 확인
- 배포 후 브라우저 새로고침 / 직접 URL 접근 / API 요청까지 같이 점검
- build 후 수동 업로드가 가능하더라도, 파일 덮어쓰기 방식을 미리 정리해두면 다음 배포가 훨씬 편합니다.
scp보다rsync --delete를 선호하는 경우가 많은 이유도 불필요한 이전 파일을 같이 정리하기 쉽기 때문입니다.- React Router를 쓰는 프로젝트라면
try_files설정은 거의 필수라고 봐도 됩니다. - 운영 중에는 “화면이 뜬다”에서 끝내지 말고, 정적 파일 캐시·API 연결·새로고침까지 같이 확인해야 실제 배포가 끝납니다.
- React 배포는 개발 서버를 띄우는 것과 다르고, build 결과물을 서비스하는 과정입니다.
- build 폴더를 올린 뒤 Nginx가 그 경로를 바라보게 해야 브라우저에서 열립니다.
- 새로고침 404는 React Router 프로젝트에서 아주 흔한 문제입니다.
- 배포 후에는 화면뿐 아니라 API, 라우팅, 캐시까지 같이 확인해야 합니다.
npm run build성공 여부 확인- 업로드 경로와 Nginx
root경로 일치 여부 확인 try_files $uri $uri/ /index.html;설정 여부 확인- 새로고침 / 직접 URL 접근 / API 호출까지 점검했는지 확인
- Q. React 배포할 때 꼭 Nginx가 있어야 하나요?
→ 꼭 Nginx만 써야 하는 건 아닙니다. 다만 리눅스 서버에서 정적 파일을 안정적으로 서비스할 때 많이 쓰는 방식이라, 실제 배포 흐름을 설명할 때 함께 보는 경우가 많습니다. - Q. build 폴더만 서버에 올리면 끝인가요?
→ 거의 맞지만, 정확히는 그다음 단계까지 봐야 합니다. 업로드한 경로를 웹서버가 제대로 바라보는지, 새로고침 시 404가 나지 않는지까지 확인해야 실제 서비스가 됩니다. - Q. React Router를 안 쓰면 `try_files` 설정이 필요 없나요?
→ 라우팅 구조에 따라 다르지만, SPA 방식으로 여러 경로를 브라우저에서 직접 여는 구조라면 필요할 가능성이 큽니다.
처음에는 React 배포가 복잡해 보여도, 실제로는 흐름이 정해져 있습니다.
- build 만들기
- 서버에 올리기
- Nginx가 파일을 바라보게 하기
- 새로고침/직접 URL 접근 확인하기
이 순서만 잡히면 처음 배포도 생각보다 어렵지 않습니다.
특히 리눅스 서버에서 React를 운영할 때는 “파일을 올렸다”에서 끝내지 말고, 웹서버 설정과 라우팅 동작까지 같이 확인하는 것이 정말 중요합니다. 여기까지 맞아야 실제 서비스라고 볼 수 있습니다.
React를 리눅스 서버에 배포할 때는 build 파일을 올리는 것에서 끝나는 게 아니라, Nginx가 그 파일을 제대로 서비스하고 라우팅까지 정상 동작하는지 확인해야 합니다.
※ 이 글은 React 정적 파일 배포 흐름을 쉽게 이해하기 위한 입문형 배포 가이드입니다. 실제 운영 환경에서는 HTTPS, 캐시 정책, 도메인 설정, CI/CD 자동 배포까지 함께 고려하면 더 안정적으로 운영할 수 있습니다.
'Front > React' 카테고리의 다른 글
| React useState 사용법 정리 | 상태 관리, 값 변경, 배열·객체 업데이트까지 (0) | 2026.04.04 |
|---|---|
| React useEffect 사용법 정리 | 실행 시점, 의존성 배열, API 호출까지 (0) | 2026.04.03 |
| React Router 사용법 | 페이지 이동, Link, 기본 라우팅 적용 방법 (2) | 2026.04.02 |
| React JSX 문법 정리 | 기본 문법, 조건부 렌더링, 리스트 렌더링까지 (0) | 2026.04.02 |
| React 프로젝트 구조 정리 | src, public, components 폴더 역할 쉽게 이해하기 (0) | 2026.04.01 |