Astro에서 npm run dev만으로는 배포 결과를 확인할 수 없는 이유

このコンテンツはまだ日本語訳がありません。

2026年5月17日

Issue

개발환경에서는 정상인데, 실제 배포 후 운영환경에서는 보이지 않는 부분이 있었다.

Astro 기반 블로그를 수정한 뒤 로컬 npm run dev로 확인했을 때는 문제가 없었다. 그런데 Firebase Hosting에 배포한 실제 페이지를 열어 보니, 개발환경에서는 정상적으로 보이던 블로그 상세 페이지의 제목과 목차가 운영환경에서는 보이지 않았다.

처음에는 배포가 잘못됐다고 생각했다. 하지만 시크릿 창에서 다시 확인해도 같은 현상이었고, GitHub Actions 배포도 정상적으로 끝난 상태였다.

즉 문제는 단순한 캐시나 배포 실패가 아니라, 개발환경에서 확인한 내용과 실제 배포 후 운영환경의 결과가 다를 수 있다는 점을 놓치고 있었다는 데 있었다.

Cause

운영환경과 같은 방식으로 결과를 확인하지 않았다는 점이었다.

로컬 npm run dev는 개발 서버이기 때문에, HMR(Hot Module Replacement), dev toolbar, 개발용 JS 경로 같은 개발 편의 기능이 함께 동작한다.

반면 실제 배포는 npm run build로 생성한 dist 결과물을 기준으로 한다. 즉 아래 두 가지는 서로 다르다.

npm run dev로 보는 개발환경
npm run build 후 dist를 정적 서버로 띄워서 보는 결과

문제는 그동안 개발 중 확인을 npm run dev에만 의존하고 있었다는 점이다.

이번 이슈의 핵심은 화면에 보이지 않는 부분이 있다는 버그 자체보다, 운영환경과 같은 방식으로 확인해야 배포 후에도 문제가 없다는 점이었다.

Resolution

운영환경과 비슷한 결과를 보려면 npm run dev가 아니라 정적 서버로 dist를 확인해야 한다.

이번 일을 계기로 배포 전 확인 방법을 바꿨다. 이제는 npm run dev로 기능과 레이아웃을 먼저 확인하되, 배포 직전에는 반드시 npm run build 후 정적 서버로 결과를 한 번 더 본다.

가장 간단한 방법은 Astro의 preview를 쓰는 것이다.

npm run build
npm run preview

또는 필요하면 아래처럼 Python 이나 Node.js 로 정적 서버를 직접 실행할 수도 있다.

Python

cd dist
python3 -m http.server 4321

Node.js

npx serve -l 4321 dist/

그 뒤 브라우저에서 아래 주소로 접근하면 된다.

http://localhost:4321

앞으로의 확인 순서는 아래처럼 하기로 했다.

npm run dev로 개발 중 기능과 화면을 확인한다.
배포 전에 npm run build를 실행한다.
npm run preview 또는 별도 정적 서버로 dist를 확인한다.
이상이 없으면 실제 배포를 진행한다.

Notes

1) `npm run dev`는 운영환경 확인용이 아니다

개발 서버는 개발 편의 기능을 포함한 환경이다.
그래서 개발 중 확인용으로는 좋지만, 실제 배포 결과와 완전히 같다고 볼 수 없다.

2) `dist`를 정적 서버로 실행해봐야 운영환경에 가까운 결과를 확인할 수 있다.

dist는 정적 빌드 결과물이다.
이 결과물을 npm run preview나 별도 정적 서버로 확인해야 운영환경과 비슷한 화면을 볼 수 있다.

3) `dist/index.html`을 직접 열면 안 된다

정적 사이트를 file://로 직접 열면 CSS, JS, asset 경로가 깨질 수 있다.
그래서 dist를 확인할 때도 반드시 HTTP 서버가 필요하다.

4) HMR이란?

HMR(Hot Module Replacement)은 개발 서버에서 수정한 파일만 즉시 교체해서 반영하는 기능이다.
예를 들어 CSS를 바꾸면 페이지 전체를 새로고침하지 않고 스타일만 바로 바뀌고, 컴포넌트를 수정하면 해당 모듈만 다시 로드될 수 있다.
이런 동작은 개발 편의 기능이므로, 실제 배포 결과와 화면이나 동작이 완전히 같다고 가정하면 안 된다.