Vite + React 빌드·배포 트러블슈팅 — 장부 관리 앱 (2)

장부 관리 데모 앱을 GitHub Pages에 올리며 밟은 Vite·React 빌드·배포 함정 기록. npm ci와 lock 정합성, tsc -b 타입 검사 차단, Tailwind v4 @apply 미적용, body overflow-hidden 전역 스타일 사고, SPA 새로고침 404를 HashRouter로 회피, base 경로와 단일 CSS 번들, Pages 배포 권한까지 순서대로 다룹니다.

 

2편: 빌드와 배포

1편에서 에디토리얼 스타일 UI를 다뤘다. 이번 편은 이 데모를 GitHub Pages에 올리며 만난 실전 트러블슈팅이다. 작은 데모라도 "빌드가 통과하고, CI가 돌고, 정적 호스팅에서 보이게" 하는 데는 잔 함정이 많았다.

1) CI 실패: npm ci vs npm install

GitHub Actions에서 빌드가 npm ci에서 실패했다. npm ci는 package-lock.json이 package.json과 정확히 일치해야 동작한다. lock 파일이 살짝 어긋나 있으면 바로 실패한다.

데모 단계에선 의존성이 자주 바뀌어 lock이 어긋나기 쉬웠다. CI에서 npm install을 쓰도록 바꿔(lock을 갱신하며 설치) 우선 통과시키고, lock 파일을 다시 생성해 동기화했다.

# 문제: lock 불일치 시 즉시 실패
- run: npm ci
# 데모 단계 해결: lock 갱신 허용
- run: npm install

> 운영 프로젝트라면 npm ci(재현 가능한 빌드)가 맞다. 다만 lock을 항상 동기화해두는 규율이 전제다. 데모처럼 의존성이 출렁이는 단계에선 npm install이 현실적이었다.

2) 빌드 에러: TypeScript와 누락된 import

빌드를 막은 또 다른 벽은 타입 에러와 누락된 import였다. 한 화면(예약 화면)에서 import가 빠져 빌드가 깨졌고, 여러 TS 에러가 남아 있었다. 데모라도 빌드 타임에 타입을 잡으니, 런타임에서 터질 버그를 미리 막을 수 있었다. 누락 import를 채우고 TS 에러를 전부 정리했다.

3) Tailwind @apply 문제

스타일에서 @apply가 제대로 처리되지 않는 문제가 있었다. @apply는 Tailwind가 빌드 시 처리하는 디렉티브라, 설정이나 처리 순서가 어긋나면 무시된다. @apply 관련 설정을 정리해 의도한 유틸리티가 적용되게 했다.

4) body의 overflow-hidden

레이아웃에서 body에 걸린 overflow-hidden이 스크롤을 막아, 콘텐츠가 잘려 보였다. 전역 스타일이 전체 레이아웃에 의도치 않은 영향을 주는 전형적인 사례다. body에서 overflow-hidden을 걷어내 스크롤을 살렸다.

5) GitHub Pages 배포 워크플로

마지막으로 GitHub Pages 배포 워크플로를 추가했다. 빌드 산출물(dist)을 Pages로 올리는 Actions를 구성했다. (Vite + Pages 조합에서 자주 만나는 _로 시작하는 경로 문제는 .nojekyll로 처리하는 게 정석이다 — 이건 다른 글에서도 다룬 적이 있다.)

작은 데모에서도 배운 것

이 앱은 규모가 작은 데모였지만, "내 PC에서 되는 것"과 "CI에서 빌드되고 정적 호스팅에서 보이는 것"은 다른 문제였다.

• CI는 lock 일관성에 엄격하다(npm ci) — 동기화 규율이 없으면 install로.
• 빌드 타임 타입 검사가 런타임 버그를 미리 잡는다.
• 전역 스타일(body overflow)은 전체에 영향 — 조심.
• 빌드 도구의 디렉티브(@apply)는 처리 순서/설정에 민감.

시리즈를 마치며

두 편에 걸쳐 장부 관리 데모를 정리했다.

• 1편: 에디토리얼 스타일 UI와 브랜드 아이덴티티 — "흔한 룩" 벗어나기
• 2편: Vite + React 빌드·배포 트러블슈팅 — 작은 데모의 잔 함정들

데모라도 "보여줄 수 있는 상태(배포)"까지 가는 데는 디자인만큼 빌드·배포의 디테일이 중요했다. 디자인으로 첫인상을 잡고, 빌드·배포로 실제로 굴러가게 만드는 — 두 가지가 다 있어야 데모가 데모로서 완성된다.