Astro 정적 블로그 배포할 때 자주 막히는 5가지
Astro 정적 사이트 배포에서 실제로 자주 막히는 지점을 빠르게 정리했습니다.
결론 먼저
대부분의 배포 실패는 코드 문제가 아니라 빌드 설정 불일치에서 나옵니다. Build command, Output directory, Node 버전, 환경변수 4개만 먼저 고정해도 사고가 크게 줄어듭니다.
가장 자주 막히는 지점 5개
- Output directory를
dist가 아닌 값으로 넣음 - Node 버전 불일치로 빌드 실패
site값 누락으로 canonical/sitemap URL 꼬임- 비공개 환경변수를 브라우저 코드에서 직접 참조
- PR 브랜치와 본 배포 브랜치 설정 불일치
| 항목 | 권장값 | 점검 포인트 |
|---|---|---|
| Build command | npm run build | 로컬에서도 동일 명령 성공 |
| Build output directory | dist | 배포 플랫폼 설정값과 일치 |
| Node version | 20 이상 권장 | 로컬/CI 버전 동기화 |
| Site URL | https://life.besl.me | sitemap/canonical 일관성 |
배포 전 체크리스트
-
astro.config.mjs에site값이 설정되어 있다. -
npm run build가 로컬에서 성공한다. - 배포 플랫폼의 Output directory가
dist다. - 필수 환경변수(예:
ADSENSE_CLIENT_ID)가 배포 환경에 등록되어 있다.
FAQ
Q1. 서버리스 함수가 꼭 필요할까요?
정적 블로그라면 대부분 필요 없습니다. 초기에는 SSG 우선이 운영비에 유리합니다.
Q2. Preview 배포와 Production 배포를 분리해야 하나요?
네. PR은 Preview, main은 Production으로 분리하면 품질 관리가 편합니다.
Q3. 배포가 느린데 정상인가요?
의존성 캐시가 비어 있으면 처음에는 느릴 수 있습니다. 이후 캐시가 쌓이면 빨라집니다.