Astro GitHub Pages 배포 base 경로 오류 3분 만에 해결하기

Astro GitHub Pages 배포 base 경로 오류 해결 방법은 astro.config.mjs 파일에 저장소 이름 기반의 경로 설정을 추가하고 정적 자산 로딩 시 접두사를 부여하는 것입니다.

열심히 작성한 정적 웹사이트를 GitHub Pages 저장소에 올린 직후 메인 페이지의 CSS 디자인이 완전히 붕괴하거나 이미지 경로가 404 에러로 일제히 깨진 경험이 있으신가요? 로컬 개발 환경인 localhost에서는 완벽하게 돌아가던 사이트가 배포 주소인 github.io 환경으로 넘어가는 순간 작동을 멈추면 당황하기 쉽습니다. 이 문제는 Astro 정적 사이트가 도메인의 최상위 루트가 아닌 하위 저장소 이름 디렉토리를 바라보지 못해서 발생하는 전형적인 파일 경로 불일치 현상입니다. 기본적인 프레임워크 초기 구동 방식이 궁금하다면 먼저 Astro 블로그 초기 설정 가이드 글을 읽어보시면 프로젝트 아키텍처를 이해하는 데 도움이 됩니다.

이 가이드를 끝까지 읽으시면 단 3분의 설정 수정만으로 GitHub Pages 배포 환경에서 스타일과 정적 자산이 깨지는 오류를 완벽하게 해결하실 수 있습니다.

Astro GitHub Pages 배포 base 경로 오류 원인 분석

Astro GitHub Pages 배포 base 경로 오류는 서브 디렉토리 환경에서 모든 절대 경로 상의 정적 자산을 기본 도메인 루트로 오인하여 참조할 때 발생합니다.

기본적으로 Astro 빌드 엔진은 브라우저에서 요청하는 파일 경로를 도메인 최상위 주소인 / 기준으로 생성합니다. 하지만 커스텀 도메인을 연결하지 않은 일반적인 GitHub Pages는 https://username.github.io/repository-name/ 형태의 서브 디렉토리 구조를 가집니다. 결과적으로 브라우저는 /repository-name/_astro/style.css에 존재하는 파일 대신 존재하지 않는 / _astro/style.css 파일을 탐색하게 되면서 404 에러가 발생합니다.

분류	로컬 개발 환경 (localhost)	GitHub Pages 환경 (유저 서브 디렉토리)
사이트 접속 주소	`http://localhost:4321/`	`https://username.github.io/my-repo/`
자산 기본 참조 경로	`/_astro/main.css`	`/my-repo/_astro/main.css` (base 필수)
base 미설정 시 결과	정상 동작	CSS, JS, 이미지 전체 404 에러 발생

이러한 주소 체계의 격차를 프레임워크 설정 수준에서 직접 연결해 주지 않으면 배포 화면은 빈 흰색 바탕만 노출됩니다.

astro.config.mjs 파일 base 및 site 설정 방법

Astro 프로젝트의 설정 파일인 astro.config.mjs에 site 주소와 base 저장소 이름을 명시하면 빌드 시 정적 자산 경로가 자동으로 교정됩니다.

프로젝트 루트 경로에 위치한 astro.config.mjs 파일을 편집기로 연 뒤 아래와 같이 두 가지 필수 프로퍼티를 명확하게 입력해주어야 합니다. site 항목에는 사용자의 GitHub Pages 기본 URL을 적고, base 항목에는 슬래시로 시작하는 저장소 이름을 정확하게 대소문자 구분하여 기재합니다.

// astro.config.mjs 파일 수정 예시
import { defineConfig } from 'astro/config';

export default defineConfig({
  // 본인의 GitHub 유저네임으로 구성된 페이지 주소 입력
  site: 'https://username.github.io',

  // 배포 대상 저장소(Repository) 이름을 슬래시로 감싸서 지정
  base: '/my-repository-name',

  // trailingSlash 옵션을 항상 유지하도록 설정하여 주소 일관성 확보
  trailingSlash: 'always',
});

만약 개인 커스텀 도메인(예: https://blog.example.com)을 저장소에 연결하여 사용할 경우에는 base 항목을 지정하지 않거나 '/'로 고정해야 합니다. 클라우드플레어를 활용한 배포 환경에 대해 더 알고 싶으시다면 정적 웹사이트 Cloudflare Pages 배포 가이드 문서를 정독해 보시길 추천합니다.

동적 라우팅 및 자산 경로 깨짐 방지용 import.meta.env.BASE_URL 활용법

마크다운 파일 내부나 Astro 컴포넌트 내부에서 하드코딩된 상대 경로는 import.meta.env.BASE_URL 변수를 결합하여 동적으로 주소를 완성해야 합니다.

HTML 내에서 단순히 <img src="/images/logo.png" />라고 서술할 경우 base 설정이 무시된 채 루트 주소로 렌더링될 위험이 큽니다. Astro가 제공하는 환경 변수를 결합하여 주소를 구성하면 로컬과 배포 환경 모두에서 절대 경로가 완벽하게 호환됩니다.

---
// src/components/Header.astro 파일 내 동적 경로 처리 예시
const baseUrl = import.meta.env.BASE_URL;
---

<header>
  <!-- 환경변수와 서브 경로를 조합하여 깨짐 없는 이미지 로딩 구현 -->
  <a href={baseUrl}>
    <img src={`${baseUrl}/favicon.svg`} alt="블로그 로고" />
  </a>
  <nav>
    <a href={`${baseUrl}/about/`}>소개 페이지</a>
  </nav>
</header>

이와 같이 모든 앵커 태그와 이미지 소스에 접두사를 안전하게 부여하면 배포 후 링크 클릭 시 발생하던 404 주소 오류가 근본적으로 차단됩니다.

GitHub Actions 자동 배포 워크플로우 구축과 .nojekyll 처리

GitHub Actions를 통해 정적 사이트를 자동 빌드할 때는 배포 폴더 루트에 .nojekyll 파일을 생성하여 정적 리소스 차단을 방지해야 합니다.

GitHub Pages는 기본적으로 파이썬 기반 지킬(Jekyll) 엔진을 거쳐 배포를 시도합니다. 이 과정에서 지킬 엔진이 언더스코어로 시작하는 _astro 폴더 내부의 번들링된 CSS 및 파이썬/자바스크립트 자산을 보안 이유로 무시하고 누락시키는 불상사가 일어납니다.

# .github/workflows/deploy.yml 자동 배포 설정 예시
name: Deploy Astro site to Pages

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Install dependencies
        run: npm ci

      - name: Build site with Astro
        run: npm run build

      # 지킬 엔진 작동을 비활성화하는 .nojekyll 빈 파일 생성
      - name: Create .nojekyll file
        run: touch ./dist/.nojekyll

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

이러한 CI/CD 워크플로우 빌드 단계를 구성해 두면 저장소에 코드를 푸시할 때마다 깨끗하게 빌드된 정적 HTML 파일이 곧바로 배포 상태로 이어집니다.

자주 묻는 질문 (FAQ)

Q. Astro에서 base 설정이 필요한 이유는 무엇인가요?

GitHub Pages처럼 도메인 루트가 아닌 서브 디렉토리 경로에 사이트가 배포될 때 정적 자산의 절대 경로가 일치하지 않아 페이지나 스타일이 깨지는 현상을 방지하기 위해 필수적입니다.

Q. import.meta.env.BASE_URL은 어떤 상황에서 사용하나요?

이미지 태그나 내부 하이퍼링크 주소를 마크다운 또는 Astro 컴포넌트 내에서 하드코딩하지 않고 설정된 base 경로를 하위 경로에 자동으로 붙여주기 위해 활용합니다.

Q. GitHub Pages 배포 시 _astro 폴더 404 에러가 나는 이유는 무엇인가요?

GitHub Pages의 기본 지킬(Jekyll) 빌더가 언더스코어(_)로 시작하는 정적 파일 폴더를 무시하기 때문이며, .nojekyll 파일을 배포 루트에 포함시키면 무사히 해결됩니다.

결론: Astro 정적 블로그 안정적 배포를 위한 최종 검크리스트

Astro 정적 블로그의 배포 장애는 대부분 경로 지정 누락과 지킬 엔진의 폴더 차단에서 시작되므로 몇 가지 핵심 설정만 수동으로 교정해주시면 깨끗하게 해결됩니다.

오늘 알아본 핵심 조치 사항을 정리하자면 아래와 같습니다.

astro.config.mjs 파일 내 site 및 base 속성값 기재
이미지 및 하이퍼링크 주소에 import.meta.env.BASE_URL 환경 변수 결합
배포 파이프라인 상에 .nojekyll 파일 생성 스크립트 추가

지금 즉시 프로젝트 설정 파일인 astro.config.mjs를 열어 base 항목을 추가하시고 오류 없는 쾌적한 배포 환경을 완성해 보시기 바랍니다.