프론트엔드 빌드와 배포는 어떻게 다르며 어떤 실행 조건으로 플랫폼을 고르나요?
빌드는 소스를 실행·배포할 형태로 만드는 과정이고 배포는 그 결과를 사용자가 접속할 환경에 놓는 작업입니다. 정적 파일만 필요한지 서버 실행도 필요한지 구분해 플랫폼을 고르세요.
본문 근거: vercel.com/docs/deployments · firebase.google.com/docs/hosting · firebase.google.com/docs/app-hosting
배포 전에 먼저 구분해야 할 것
배포 문제를 빠르게 해결하려면 플랫폼 이름보다 먼저 애플리케이션 구조를 확인해야 합니다.
소스 코드
↓
의존성 설치
↓
build
↓
배포 산출물 또는 서버 런타임 생성
↓
호스팅 플랫폼
↓
도메인 / HTTPS
↓
사용자 요청
이 흐름에서 어느 단계가 실패했는지에 따라 확인 방법이 완전히 달라집니다.
예를 들어 npm ci가 실패하면 DNS를 확인할 이유가 없습니다. 반대로 build가 성공했는데 커스텀 도메인만 열리지 않는다면 package-lock.json을 수정할 이유도 없습니다.
build와 deploy 차이
build는 소스 코드를 배포 가능한 형태로 만드는 과정입니다.
예를 들어 Next.js 프로젝트에서는 보통 다음 명령을 실행합니다.
npm run build
build가 성공했다는 것은 현재 프로젝트 설정과 코드가 빌드 단계를 통과했다는 뜻입니다.
deploy는 그 결과를 실제 실행 환경에 올리는 과정입니다.
build 성공
≠
Production 서비스 정상
Production 정상
=
build + runtime + env + routing + network + domain 검증
따라서 배포 글에서는 “배포 성공” 표시만 확인하지 않고 실제 URL에서 핵심 화면과 기능도 확인해야 합니다.
정적 배포와 서버 런타임
가장 먼저 확인할 것은 배포할 결과물이 정적 파일만으로 동작하는지입니다.
Vite 프로젝트를 일반적으로 build하면 dist 같은 정적 산출물이 만들어집니다.
dist/
├─ index.html
└─ assets/
이런 프로젝트는 정적 호스팅에 잘 맞습니다.
Next.js Server Component는 빌드 시 정적으로 렌더링할 수 있고 GET Route Handler도 정적 산출물을 만들 수 있습니다. 기능 이름만으로 서버 런타임이 필요하다고 판단하지 않습니다. 요청별 동적 데이터, SSR, Server Action처럼 요청 시 서버 실행이 필요한 기능을 사용하면 정적 파일만 복사해서 끝나지 않습니다.
정적 파일
HTML / CSS / JS / 이미지
→ 파일을 CDN에서 제공
서버 런타임
SSR / Route Handler / Server Action
→ 요청 시 코드 실행 환경 필요
Firebase 공식 문서도 정적 웹 앱에는 Hosting을, Next.js 같은 풀스택 프레임워크 앱에는 App Hosting을 주요 선택지로 안내합니다. Vercel 역시 Next.js의 서버 런타임과 배포 흐름을 관리형으로 연결할 수 있습니다.
배포 플랫폼 선택 기준
플랫폼을 먼저 정한 뒤 코드를 맞추기보다 프로젝트 요구사항을 먼저 적는 편이 좋습니다.
| 확인 항목 | 질문 |
|---|---|
| 렌더링 | 정적 파일만 필요한가, SSR이 필요한가 |
| 서버 기능 | 요청 시 실행되는 Route Handler나 서버 함수가 있는가 |
| 데이터 | 외부 DB나 API와 연결하는가 |
| 환경 | Preview와 Production을 분리해야 하는가 |
| 도메인 | 커스텀 도메인이 필요한가 |
| 운영 | 로그와 롤백이 필요한가 |
TaskFlow 과정에서는 주 실습 경로를 Vercel Production으로 잡습니다.
이유는 “Vercel이 항상 더 좋다”가 아니라, Next.js TaskFlow를 실제 Production 환경에 연결하고 Preview / Production / 로그 / deployment 단위 진단을 배우기에 적절하기 때문입니다.
Firebase Hosting과 App Hosting은 별도 회차에서 배포 모델을 비교합니다.
Preview와 Production
운영 배포에서는 환경을 구분해야 합니다.
로컬
개발자 PC
Preview
브랜치 / PR 단위 검토 환경
Production
실제 사용자에게 제공하는 운영 환경
환경변수도 같은 값이라고 가정하면 안 됩니다.
예를 들어 다음 값은 환경에 따라 달라질 수 있습니다.
API_BASE_URL
AUTH_CALLBACK_URL
DATABASE_URL
PUBLIC_SITE_URL
Vercel에서는 환경변수를 Production, Preview, Development 같은 범위로 구분할 수 있습니다. 값을 변경했다면 해당 값을 사용하는 새로운 배포가 필요할 수 있으므로 “설정 저장”과 “현재 deployment에 반영”도 구분해야 합니다.
배포 완료 기준
이 과정에서는 배포 완료를 다음처럼 판단합니다.
1. 로컬 npm run build 통과
2. CI 설치·build 통과
3. Production deployment 성공
4. Production URL 응답 확인
5. 핵심 화면과 기능 확인
6. 환경변수 누락 없음
7. 커스텀 도메인과 HTTPS 확인
8. 현재 배포 commit을 식별 가능
9. 로그 확인 위치를 알고 있음
10. 이전 정상 버전으로 되돌리는 절차가 있음
단순히 대시보드에 초록색 Success가 표시되었다고 전체 검증을 끝내지 않습니다.
장애를 계층별로 나누기
배포 오류는 다음처럼 분류하면 원인 범위를 빠르게 줄일 수 있습니다.
Install
npm ci / lockfile / package manager
Build
TypeScript / lint / build command / env
Runtime
서버 함수 / API / DB / 실행 환경
Routing
404 / rewrite / redirect / asset path
Network
DNS / TLS / CORS / proxy
Cache
브라우저 / CDN / 오래된 deployment
Operation
로그 / 알림 / 롤백 / 장애 기록
예를 들어 404만 보고 rewrite를 수정하기 전에 다음을 먼저 구분합니다.
도메인 자체가 잘못 연결됨
vs
앱은 열리지만 특정 route가 없음
vs
rewrite 대상 경로가 없음
vs
정적 자산만 404
같은 증상처럼 보여도 원인은 다를 수 있습니다.
11회 학습 순서
01 배포 전체 로드맵
02 Firebase Hosting / App Hosting
03 SSH / SFTP / FTP
04 Vercel 첫 Production 배포
05 커스텀 도메인 / DNS / HTTPS
06 GitHub Actions npm ci
07 Vercel build 실패
08 Vercel 404 / rewrites
09 환경변수 / proxy / cache / header
10 로그 / 알림 / rollback / incident
11 전체 배포 오류 해결 허브
앞 회차에서 만든 운영 기준을 뒤 회차가 그대로 사용합니다.
이 주제만 따로 연습하기
배포 계정 없이 다음 가상 앱의 계획을 작성합니다. 입력은 “Vite로 만든 안내 페이지, 로그인·서버 API 없음, 빌드 결과 dist/index.html과 assets, 대표 경로 /와 /help”입니다. 이 입력은 특정 TaskFlow 프로젝트의 상태를 기억할 필요가 없습니다.
| 항목 | 작성할 결과 |
|---|---|
| 산출물 | 정적 HTML·CSS·JavaScript |
| 런타임 | 요청마다 실행할 앱 서버는 현재 요구에 없음 |
| 검증 | /와 /help를 직접 열고 새로고침, CSS/이미지 응답 확인 |
| 복구 | 직전 정상 배포 식별자와 같은 경로 재검사 |
자가 확인: /help에 요청 시 비밀키를 사용하는 서버 기능이 추가되면 정적 파일만으로 충분할까요? 서버 런타임 또는 별도 백엔드가 필요하므로 계획을 다시 평가합니다. 표 작성은 배포 성공 기록이 아닙니다.
학습 완료 체크리스트
- build와 deploy 차이를 설명할 수 있습니다.
- 정적 파일과 서버 런타임을 구분할 수 있습니다.
- 프로젝트 요구사항을 보고 배포 플랫폼을 고를 수 있습니다.
- Preview와 Production 환경을 구분할 수 있습니다.
- 배포 장애를 install, build, runtime, routing, network, cache 계층으로 나눌 수 있습니다.
- 과정의 최종 결과물이 TaskFlow Production과 운영 runbook이라는 것을 이해했습니다.
선택 실습: 할 일 앱에 적용하기
TaskFlow는 작업을 관리하는 예제 앱입니다. 이 선택 실습에서는 앱을 배포하고 서버·설정·운영 결과를 확인합니다.
이번 주제: 프론트엔드 배포 로드맵: Vercel·Firebase Hosting·App Hosting 선택 기준.
선택: 연재 프로젝트와 전체 자료
연재 프로젝트를 이어 만드는 분을 위한 자료입니다. 이 글의 개념과 예제만 찾으셨다면 필요한 파일과 실행 방법만 펼쳐보세요.
TaskFlow 프로젝트 적용
이 글부터 시작하는 전체 프로젝트
시작 ZIP — deploy-step-00-build-ready-full-20260928을 새 폴더에 풀고, 이번 단계 완료 ZIP은 다른 폴더에 풀어 비교합니다. ZIP 안 프로젝트 폴더의 package.json 위치가 실행 루트입니다.
출발점은 Next.js 누적 TaskFlow와 같은 38단계 소스입니다. 프로젝트에는 홈·로그인·개인 작업 화면, 작업 추가·완료·삭제, Route Handler와 캐시 예제가 들어 있습니다. 설치 버전을 고정한 package-lock.json도 포함합니다.
이번 변경 이유: 배포 계획과 확인 기준을 문서화합니다.
docs/deployment-plan.md
- 시작 ZIP을 풀고
npm ci로 의존성을 설치합니다. Node.js 24와 npm을 사용합니다. - 위 변경 파일을 아래 전체 내용 또는 완료 ZIP의 같은 경로와 대조해 적용합니다. 다른 앱 파일은 유지합니다.
npm run typecheck,npm run build를 실행합니다. 오류가 있으면 첫 오류의 파일·명령을 기록하고 해결한 뒤 진행합니다.npm run setup-auth로 일회용 로컬 학습 계정을 설정한 후npm run dev를 실행합니다. 생성된.env.local과 입력 값은 공유하지 않습니다.
예상 결과: 홈과 로그인 화면은 공개됩니다. 로그인 전 /tasks는 로그인 화면으로 이동하고 /api/tasks는 401을 반환합니다. 로그인 후 작업 목록에서 추가·완료·삭제를 확인합니다. /cache-lab의 별도 캐시 실습은 npm run cache-api가 필요합니다.
저장·운영 범위: 작업은 단일 Node 프로세스 메모리에 저장되고 인증은 학습용 계정 예제입니다. 서버 재시작·서버리스 인스턴스 사이의 데이터 유지는 보장하지 않습니다. 로컬 실행 확인과 실제 운영 서비스 구축은 구분하며, 원격 배포·DNS·SSH·CI·롤백 결과는 직접 실행한 항목만 문서에 기록합니다.
전체 파일·코드 보기
이번 단계의 변경 파일 전체
docs/deployment-plan.md
# TaskFlow Deployment Plan
## Build
- package manager: npm
- install: npm ci
- build: npm run build
## Primary deployment
- platform: Vercel
- environment: Production
## Alternative deployment
- Firebase Hosting: static output일 때 검토
- Firebase App Hosting: server runtime이 필요할 때 검토
## Verification
- Production URL 응답
- 주요 화면 확인
- 환경변수 확인
- 주요 route 확인
- 현재 commit 확인
- rollback 가능 여부 확인
나머지 앱 소스와 잠금 파일은 전체 완료 ZIP에 있습니다. 기존 코드 조각은 설명용이며 위 전체 변경 파일과 ZIP이 이 누적 실습의 기준입니다. 다음 글에는 이번 완료 ZIP을 시작본으로 가져갑니다.
이 과정의 시작점은 다음 조건을 만족하는 TaskFlow입니다.
TaskFlow
- GitHub 저장소에 push 가능
- npm install 또는 npm ci 가능
- npm run build 통과
- 로컬 실행 가능
- 실제 비밀값이 저장소에 포함되지 않음
이 회차는 아래 전체 TaskFlow 시작 ZIP을 기준으로 진행합니다. 이전 글의 코드를 모으지 않아도 되며, 완료 ZIP에는 이번 변경과 기존 앱 기능이 함께 들어 있습니다.
deployment-plan.md
# TaskFlow Deployment Plan
## Build
- package manager: npm
- install: npm ci
- build: npm run build
## Primary deployment
- platform: Vercel
- environment: Production
## Alternative deployment
- Firebase Hosting: static output일 때 검토
- Firebase App Hosting: server runtime이 필요할 때 검토
## Verification
- Production URL 응답
- 주요 화면 확인
- 환경변수 확인
- 주요 route 확인
- 현재 commit 확인
- rollback 가능 여부 확인
실제 도메인과 비밀값은 이 문서에 직접 적지 않습니다.
docs/deployment-plan.md
# TaskFlow Deployment Plan
## Build
- package manager: npm
- install: npm ci
- build: npm run build
## Primary deployment
- platform: Vercel
- environment: Production
## Alternative deployment
- Firebase Hosting: static output일 때 검토
- Firebase App Hosting: server runtime이 필요할 때 검토
## Verification
- Production URL 응답
- 주요 화면 확인
- 환경변수 확인
- 주요 route 확인
- 현재 commit 확인
- rollback 가능 여부 확인
README.md
# 배포·서버 01 — deploy-step-01-roadmap
이 ZIP은 배포 준비·운영 문서와 해당 회차 설정/코드 조각을 누적한 적용 자료입니다. 실행 앱 전체는 포함하지 않습니다. 기존 deploy-step-00-build-ready 프로젝트에 해당 파일을 검토하여 적용하세요. 이 ZIP 루트에서 npm ci/build를 실행하는 구조가 아닙니다.
이 자료에는 실제 배포·DNS 변경·SSH 접속·메일/알림·롤백 결과가 없습니다. 운영 작업은 독자가 본인 환경과 권한을 확인한 후 수행해야 합니다. 문서의 확인 항목은 수행할 체크리스트이며 이미 통과했다는 기록이 아닙니다.
이전 체크포인트
deploy-step-00-build-ready
현재 TaskFlow는 로컬 build가 가능한 상태라고 가정합니다.
이번 변경
코드 기능은 바꾸지 않고 배포 기준 문서를 추가합니다.
docs/
└─ deployment-plan.md
실행 확인
npm ci
npm run build
이 글에서는 실제 클라우드 배포를 아직 실행하지 않습니다. 로컬 build가 통과하고 배포 계획이 문서화되면 다음 회차로 넘어갑니다.
참고용 문서·최소 예제 코드
아래 기존 문서·설정 예시는 변경 이유를 설명합니다. 실제 누적 앱의 전체 소스는 위의 전체 완료 ZIP에 있으며, 다음 회차의 시작본으로 그대로 사용합니다.
완료 체크포인트
deploy-step-01-roadmap
실습 경로·결과·복구
독자 질문
TaskFlow는 어떤 산출물을 어디에 배포하며, 완료를 무엇으로 판단할까요?
배포 전제
기존 TaskFlow 저장소와 package-lock.json, GitHub push 권한이 필요합니다. 이 회차는 계획 단계이며 Production 계정·도메인을 요구하지 않습니다.
실행 단계
- package.json의 scripts.build를 읽고 프로젝트 루트에서 npm ci, npm run build를 실행합니다. 성공 시 종료 코드 0과 실제 산출물 위치를 적습니다.
- 서버 요청마다 실행되는 기능이 있는지 확인하고 docs/deployment-plan.md에 주 경로 Vercel, Firebase 대안의 선택 근거, 주요 확인 경로 2개, 실패 시 되돌릴 이전 정상 배포 식별 방법을 적습니다.
- 결과 문서에 실제 실행 여부를 ‘실행/미실행’으로 표시합니다. CI 성공, URL 응답, 롤백은 계획을 적었다는 이유로 완료 처리하지 않습니다.
성공·실패 확인
문서에 build 명령·산출물·주/대안 경로·검증 URL 자리표시자·복구 기준이 각각 있으면 계획 작성 성공입니다. npm ci에서 lockfile 오류가 나면 6회차의 lockfile 점검을 따릅니다. build 실패는 오류 행을 저장하고 수정 전에는 배포를 진행하지 않습니다.
복구와 검증 상태
계획이 잘못되었다면 변경 전 docs/deployment-plan.md를 Git에서 비교·복원하고 실제 프로젝트의 build 결과에 맞춰 다시 작성합니다. Production 배포·도메인·롤백 결과는 이 글에서 미확인입니다.
다음 학습
다음 글에서는 Firebase Hosting과 App Hosting을 예로 들어 정적 산출물과 서버 런타임의 차이를 더 구체적으로 확인합니다.
다음 글: Firebase Hosting App Hosting 차이: 정적 배포와 SSR 기준
다음 회차 확인 과제: 02회차에서는 실제 build 산출물과 서버 실행 기능을 목록으로 적고 Firebase Hosting과 App Hosting의 선택 근거를 완성합니다.
공식 문서
공식 문서 확인 기준: 2026-09-21
체크포인트 다운로드
글 소개·학습 준비·전체 목차
배포·서버 · 1 / 11 · 필수 길잡이 · 배포 로드맵
프론트엔드 프로젝트를 “배포했다”는 말은 단순히 build 명령이 성공했다는 뜻이 아닙니다. 사용자가 접속할 URL이 생기고, 필요한 런타임과 환경변수가 준비되며, 도메인과 HTTPS가 연결되고, 문제가 생겼을 때 어떤 버전에서 무엇이 실패했는지 추적할 수 있어야 실제 운영 배포에 가깝습니다.
상단은 작은 가상 앱의 배포 계획으로 각 기술의 역할을 익힙니다. 하단의 연속 실습은 독자가 준비한 앱에 배포 문서와 설정을 적용하며 실제 결과를 기록하는 경로입니다.
이번 글에서 배우는 내용
- build와 deploy의 차이
- 정적 산출물과 서버 런타임의 차이
- Vercel, Firebase Hosting, Firebase App Hosting을 고르는 기준
- Preview와 Production 환경의 차이
- 환경변수, 도메인, HTTPS가 배포에서 맡는 역할
- 배포 장애를 build / runtime / network 계층으로 나누는 방법
- 11회차 동안 TaskFlow가 어떻게 운영 가능한 상태로 확장되는지
선수 지식
다음 내용은 알고 시작하는 편이 좋습니다.
- Git과 GitHub의 기본 push 흐름
- Node.js와 npm 사용법
- package.json의 scripts
- Next.js 또는 Vite 프로젝트의 build 명령
- 환경변수의 기본 개념
- HTTP 요청과 응답의 기본 개념
목차
이 글이 도움이 되었나요?
읽음 기록
읽음 — / 전체 11개 · 필수 7개
새 글 받아보기
RSS 리더에서 BlogFlow의 새 글을 확인할 수 있습니다.
