Astro 작업을 하다 보면 이런 일이 있다.
pnpm dev에서는 정상
pnpm build도 성공
그런데 배포 후 페이지가 깨짐또는:
로컬 dev에서는 이미지가 보임
dist를 열면 이미지가 안 보임
GitHub Pages에서는 검색이 안 됨이럴 때는 dev 서버와 build 결과가 같은 환경이 아니라는 점부터 봐야 한다.
dev 서버는 관대하다
개발 서버는 빠른 개발을 위해 많은 것을 도와준다.
- HMR
- 모듈 해석
- 소스맵
- 개발용 경로 처리
- 임시 변환
그래서 dev에서는 되는 코드가 build에서는 다르게 동작할 수 있다.
정적 배포 사이트라면 최종 기준은 항상 dist다.
먼저 build를 돌린다
문제가 생기면 첫 단계는 단순하다.
pnpm run build이 단계에서 에러가 나면 배포 문제가 아니라 빌드 문제다.
Astro check가 포함되어 있다면 타입과 content schema 오류도 같이 잡을 수 있다.
frontmatter 날짜 오류
필수 description 누락
잘못된 import
존재하지 않는 이미지이런 문제는 배포 전에 잡는 게 좋다.
dist를 기준으로 확인한다
빌드가 성공했다면 dist 결과를 기준으로 확인해야 한다.
개발 서버가 아니라 실제 배포될 파일을 보는 것이다.
확인할 것:
dist/index.html
dist/category/.../index.html
dist/pagefind/
dist/images/
dist/sitemap-index.xml정적 파일이 없으면 배포 후에도 당연히 없다.
이미지 경로를 본다
가장 흔한 문제는 이미지 경로다.
markdown에서 public 이미지를 쓴다면 보통 루트 기준 경로가 단순하다.
반대로 상대 경로를 쓰면 글 파일 위치에 따라 깨질 수 있다.
빌드 결과에서 이미지 요청이 404인지 확인하면 빠르다.
base path 문제를 의심한다
GitHub Pages에서 프로젝트 페이지로 배포하는 경우 base path가 문제가 될 수 있다.
예를 들어:
https://user.github.io/repo/이 구조라면 루트 경로 /images/...가 예상과 다르게 동작할 수 있다.
커스텀 도메인을 쓰는지,
프로젝트 하위 경로를 쓰는지에 따라 설정이 달라진다.
검색과 광고는 페이지 전환도 본다
Astro에서 View Transitions를 쓰면 페이지 이동이 일반 새로고침과 다르게 동작할 수 있다.
이때 검색이나 광고처럼 클라이언트 스크립트에 의존하는 기능은 다시 초기화해야 할 수 있다.
확인할 이벤트:
document.addEventListener("astro:page-load", init);
document.addEventListener("astro:after-swap", init);dev에서 우연히 되는 것처럼 보여도,
배포 후 페이지 이동에서 누락될 수 있다.
환경 변수는 빌드 시점에 결정된다
Astro의 공개 환경 변수는 빌드 시점에 들어간다.
그래서 로컬 .env에는 있는데 GitHub Actions에는 없으면 배포 결과가 달라진다.
확인할 것:
PUBLIC_ 접두사 환경 변수
GitHub Actions secrets
배포 workflow env검색엔진 인증 태그나 분석 코드 같은 값은 이 문제에 걸리기 쉽다.
디버깅 순서
나는 보통 이렇게 본다.
1. pnpm run build 통과 여부
2. dist에 필요한 파일이 있는지
3. 배포된 URL에서 404가 있는지
4. console error가 있는지
5. base path가 맞는지
6. 페이지 전환 후 스크립트가 다시 실행되는지
7. 환경 변수가 배포 환경에도 있는지이 순서로 보면 막연한 “배포 후 깨짐”을 꽤 빨리 좁힐 수 있다.
오늘 포인트
Astro dev 서버는 개발 편의를 위한 환경이고,
build 결과는 실제 배포될 환경이다.
둘이 항상 같다고 보면 안 된다.
특히 아래 문제는 build 결과 기준으로 확인해야 한다.
- 이미지 경로
- base path
- 검색 색인
- sitemap/RSS
- 클라이언트 스크립트 재초기화
- 환경 변수
한 줄 요약
Astro에서 dev에서는 되는데 배포 후 깨진다면 dist 결과와 실제 배포 URL을 기준으로 경로, 정적 파일, 스크립트 초기화 순서부터 확인해야 한다.