자동 실행 검증 A · Ubuntu 24.04 · Astro 7.3.5 · Node 22.23 · 2026-09-25게시 2026-09-25최종 확인 2026-09-25읽기 11분

GitHub Pages에 배포한 Astro 사이트 CSS·JS 404 오류 해결 (site·base 설정)

GitHub Pages 프로젝트 사이트에 배포한 Astro 사이트에서 CSS·JS가 404로 깨질 때, base 설정 누락이 원인인 경우를 astro.config의 site·base 값과 BASE_URL로 해결하는 방법을 정리한다.

30초 요약

Astro는 빌드 결과에 들어가는 CSS·JS 링크에 base 설정값을 접두사로 붙인다(base 설정 문서). GitHub Pages 프로젝트 사이트(커스텀 도메인이 없는 저장소)는 https://<사용자명>.github.io/<저장소명>/ 형태로 서빙되는데, astro.config에 site만 채우고 base를 저장소 이름으로 맞추지 않으면 빌드된 HTML의 링크가 루트 기준(/_astro/xxx.css)으로 나가고, 실제 파일은 /<저장소명>/_astro/xxx.css에 있어 두 경로가 어긋난다. 브라우저는 HTML에 적힌 그대로 루트 경로를 요청하므로 CSS·JS가 404로 뜨고 페이지 스타일이 깨진다. 공식 배포 가이드는 이 경우 “모든 내부 링크에 base 값을 접두사로 붙여야 한다”고 명시한다(GitHub Pages 배포 가이드). 해결은 astro.config에 site·base를 저장소 구조에 맞게 채우고, 직접 쓰는 절대경로에는 import.meta.env.BASE_URL을 붙이는 것이다.

증상/목표

GitHub Pages에 배포한 Astro 사이트에 접속하면 다음 증상이 나타난다.

  • 브라우저 개발자 도구 Network 탭에 CSS·JS 요청이 404로 표시된다
  • 콘솔에 Failed to load resource: the server responded with a status of 404 같은 에러가 쌓인다
  • 페이지 HTML은 로드되지만 스타일이 전혀 적용되지 않거나(무스타일 페이지), 클라이언트 스크립트가 동작하지 않는다
  • 로컬 astro dev·astro preview에서는 멀쩡했는데 GitHub Pages에 올리고 나서만 깨진다

이 증상은 주로 https://<사용자명>.github.io/<저장소명>/ 형태로 서빙되는 프로젝트 사이트에서 나타난다. <사용자명>.github.io 저장소(사용자·조직 사이트) 자체나 커스텀 도메인을 쓰는 경우는 사이트가 도메인 루트에서 서빙되므로 이 문제를 겪지 않는다.

목표는 Astro의 site·base 설정을 실제 배포 경로에 맞게 채워서, 빌드된 HTML이 가리키는 자산 경로와 GitHub Pages에 실제로 올라간 파일 경로를 일치시키는 것이다.

원인

Astro 설정 문서는 base를 이렇게 정의한다.

The base path to deploy to. Astro will use this path as the root for your pages and assets both in development and in production build.

기본값은 '/'이고, 이 값을 바꾸면 astro dev 서버도 그 경로에서 시작하고, 정적 자산 import·URL에도 이 접두사가 붙는다. 코드에서는 import.meta.env.BASE_URL로 이 값을 읽을 수 있다(base 설정 문서).

GitHub Pages는 저장소 종류에 따라 사이트가 서빙되는 경로가 다르고, Astro의 GitHub Pages 배포 가이드는 이를 세 경우로 나눠 설명한다.

  1. 사용자·조직 사이트(저장소 이름이 <사용자명>.github.io인 특수 저장소): https://<사용자명>.github.io에서 도메인 루트로 서빙된다. site만 이 주소로 설정하면 되고, base는 기본값 '/'를 그대로 쓴다
  2. 프로젝트 사이트(그 외 일반 저장소): https://<사용자명>.github.io/<저장소명>/에서 서빙된다. 가이드는 “GitHub Pages will publish your website at an address that depends on both your username and your repository name”이라고 밝히고, base를 저장소를 가리키는 값으로 설정하라고 명시한다(GitHub Pages 배포 가이드)
  3. 커스텀 도메인: 어느 저장소든 커스텀 도메인을 연결하면 그 도메인 루트에서 서빙된다. 가이드는 이 경우 “base 값을 제거하고 site를 커스텀 도메인으로 갱신하라”고 안내한다(같은 문서)

2번(프로젝트 사이트)에서 base를 저장소 이름으로 설정하지 않으면, Astro는 base 기본값 '/'를 기준으로 CSS·JS·이미지 경로를 만든다. 그 결과 HTML에는 /_astro/xxx.css처럼 루트 기준 경로가 들어가지만, 실제 파일은 GitHub Pages가 /<저장소명>/_astro/xxx.css에 올려 둔 상태다. 브라우저는 HTML에 적힌 경로 그대로 요청하므로 404가 난다.

가이드는 base를 설정했을 때 따라오는 조건도 함께 명시한다. “모든 내부 페이지 링크에도 base 값을 접두사로 붙여야 한다”는 것이다. 예시로 <a href="/my-repo/about">About</a>을 든다(같은 문서). 즉 base는 Astro가 스스로 만들어내는 자산(번들된 CSS·JS, astro:assets로 처리한 이미지 등) 경로에는 자동으로 붙지만, 코드에 직접 적은 절대경로(내비게이션 링크, public/ 폴더의 파일을 가리키는 <img src="/logo.png"> 등)에는 자동으로 붙지 않는다. 이런 경로는 작성자가 직접 import.meta.env.BASE_URL을 붙여야 한다.

사용자·조직 사이트는 base를 그대로, 프로젝트 사이트는 base를 저장소 이름으로, 커스텀 도메인은 base를 없앤다. 프로젝트 사이트에서 base를 안 넣으면 /_astro/ 요청이 404가 된다사용자명.github.io 저장소일반 저장소커스텀 도메인 연결base를 안 넣으면어떤 저장소·주소인가사용자·조직 사이트: site만 설정, base는'/'프로젝트 사이트: base를 '/저장소명'으로커스텀 도메인: base 제거, site는도메인으로HTML이 /_astro/… 를 요청 → 404
GitHub Pages 배포 형태에 따른 site·base 설정 (보라 = 사람 · 초록 = 외부 · 회색 = 조건)

해결 방법

1. 배포 형태부터 확인하기

저장소 이름이 <사용자명>.github.io(또는 <조직명>.github.io)인지, 그 외 일반 저장소(프로젝트 사이트)인지, 커스텀 도메인을 쓰는지부터 확인한다. 세 경우의 site·base 값이 다르기 때문이다.

2. astro.config에 site·base 채우기

프로젝트 사이트라면 site는 GitHub Pages 루트 주소, base는 저장소 이름으로 설정한다.

// astro.config.mjs — 프로젝트 사이트(https://astronaut.github.io/my-repo/)
import { defineConfig } from 'astro/config';
export default defineConfig({
site: 'https://astronaut.github.io',
base: '/my-repo',
});

사용자·조직 사이트(<사용자명>.github.io 저장소)라면 base를 빼고 site만 설정한다.

// astro.config.mjs — 사용자·조직 사이트(https://astronaut.github.io/)
import { defineConfig } from 'astro/config';
export default defineConfig({
site: 'https://astronaut.github.io',
});

3. 직접 쓰는 절대경로에 BASE_URL 붙이기

내비게이션 링크나 public/ 폴더 이미지처럼 코드에 직접 절대경로를 적은 곳은 base가 자동으로 붙지 않으므로 import.meta.env.BASE_URL을 직접 붙인다. 이때 ${BASE_URL}about처럼 단순히 문자열만 이어 붙이면, trailingSlash 기본값('ignore')에서는 base: '/my-repo'(끝 슬래시 없음)가 그대로 BASE_URL에 반영되어 ${BASE_URL}about이 /my-repoabout처럼 끝 슬래시 유무에 따라 깨질 수 있다. 끝 슬래시가 있든 없든 항상 올바르게 이어 붙이도록, 경로를 합치기 전에 슬래시를 정리하는 작은 함수를 하나 둔다.

---
function withBase(path: string) {
const base = import.meta.env.BASE_URL.replace(/\/$/, '');
return `${base}/${path.replace(/^\//, '')}`;
}
---
<a href={withBase('about')}>About</a>
<img src={withBase('logo.png')} alt="logo" />

import로 불러오는 이미지(astro:assets의 <Image>·getImage)나 CSS의 url()처럼 Astro 빌드 파이프라인이 처리하는 자산은 신경 쓰지 않아도 된다. Astro가 최종 경로에 base를 자동으로 반영한다.

4. GitHub Actions 배포 워크플로 점검하기

withastro/action으로 빌드하고 actions/deploy-pages로 배포하는 구성이 공식 가이드가 제시하는 기본 형태다(GitHub Pages 배포 가이드).

name: Deploy to GitHub Pages
on:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout your repository using git
uses: actions/checkout@v7
- name: Install, build, and upload your site
uses: withastro/action@v6
deploy:
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v5

저장소 Settings → Pages에서 “Build and deployment” 소스를 “GitHub Actions”로 선택해야 이 워크플로가 실제로 배포된다(같은 문서). 이 설정이 여전히 브랜치 기반(Jekyll 빌드)으로 남아 있으면 워크플로가 배포한 결과가 반영되지 않는다.

5. 커스텀 도메인으로 옮길 때 base 되돌리기

나중에 커스텀 도메인을 연결한다면 base를 제거(또는 기본값 '/')하고 site를 커스텀 도메인으로 바꾼다. 가이드가 명시하는 순서다(같은 문서). base를 저장소 이름으로 남겨 두면 커스텀 도메인에서는 반대로 모든 자산 경로가 존재하지 않는 하위 경로를 가리키게 되어 같은 증상(404)이 재발한다.

이 블로그(blog.hexahub.co.kr)도 템플릿 기본 설정이 CI 빌드에서 base를 /blog로 잡고 있어, 커스텀 도메인에 맞게 site를 https://blog.hexahub.co.kr, base를 '/'로 고쳤다.

배포 워크플로 전체는 Astro 블로그를 GitHub Actions로 배포하기에, 커스텀 도메인을 붙이는 방법은 GitHub Pages 서브도메인 연결에 정리했다.

확인

base 유무가 실제로 자산 경로를 어떻게 바꾸는지, GitHub Pages 프로젝트 경로를 흉내 낸 로컬 서버(/myrepo)에서 재현해 확인했다.

  1. base를 설정하지 않은(기본값 '/') 상태로 최소 Astro 프로젝트를 빌드하고, HTML에 박힌 CSS 링크가 /_astro/... 형태로 루트 기준인지 확인한다
  2. 빌드 결과를 /myrepo/ 경로 아래에 그대로 올려 두고 정적 서버로 띄운 뒤, HTML에 적힌 경로(/_astro/..., 즉 /myrepo 없이)로 요청해 404가 나는지 확인한다 — 이것이 “루트 기준 경로 vs 실제 파일 위치(/myrepo/_astro/...)가 어긋나는 상황”의 재현이다
  3. base: '/myrepo'로 설정을 바꿔 다시 빌드하고, HTML의 CSS 링크가 /myrepo/_astro/...로 바뀌는지, 같은 서버에서 이 경로로 요청하면 200이 오는지 확인한다
CI 실행 결과 · 수정 전 재현 1건 · 수정 후 6/6 단계 성공
검증 환경 4항목
OSUbuntu 24.04.5
Astro7.3.5
Node22.23.2
실행 날짜2026-09-25
실행 기록
[PASS] astro 패키지 설치
[PASS] base 미설정(기본값 /) 상태로 빌드 성공
[PASS] 빌드 결과 HTML에서 CSS 링크를 찾았다
수정 전 재현 · 예상된 실패 1건 재현됨base 미설정: GitHub Pages 프로젝트 경로(/myrepo)를 흉내 낸 로컬 서버에 빌드 결과를 올려 두고, HTML에 적힌 그대로(루트 기준) 요청한다
[XFAIL] GitHub Pages 프로젝트 경로를 흉내 낸 로컬 서버(/myrepo)에서 base 없이 빌드된 /_astro/index.BkcuV1Gg.css 요청 — 예상된 실패 재현됨 (/^404 .*_astro.*\.css$/)
    > 404 http://127.0.0.1:8080/_astro/index.BkcuV1Gg.css
수정 후 확인 · 3/3 단계 성공base를 /myrepo로 설정하고 다시 빌드했다
[PASS] base를 /myrepo로 설정하고 다시 빌드 성공
[PASS] 빌드 결과 HTML의 CSS 링크에 /myrepo 접두사가 붙었다
[PASS] GitHub Pages 프로젝트 경로를 흉내 낸 로컬 서버(/myrepo)에서 base 적용 후 /myrepo/_astro/index.BkcuV1Gg.css 요청이 200
이 결과는 글의 명령어를 GitHub Actions의 깨끗한 환경에서 그대로 실행해 자동으로 붙인 것입니다.

주의

  • base 값은 앞에 슬래시를 붙이고 끝에는 보통 슬래시를 붙이지 않는다(/my-repo). trailingSlash 설정이 'never'면 BASE_URL에서 끝 슬래시가 빠지고, 'always'면 끝 슬래시가 항상 붙는다(base 설정 문서)
  • 커스텀 도메인으로 옮긴 뒤 base를 저장소 이름으로 그대로 두면, 이번에는 반대 방향으로 모든 자산 경로가 깨진다. 배포 대상을 바꿀 때마다 site·base 조합을 다시 확인한다
  • 이 글이 다루는 404는 base 설정 문제다. 브랜치 배포(빌드 결과를 gh-pages 브랜치 등에 커밋해 그 브랜치를 발행 소스로 쓰는 방식)를 쓰면 GitHub Pages가 배포 콘텐츠를 Jekyll로 처리하면서 언더스코어(_)로 시작하는 폴더·파일을 무시하는데, Astro의 기본 자산 폴더 이름이 _astro라서 base를 맞게 설정해도 CSS·JS 파일 자체가 배포되지 않아 404가 나는 사례가 보고돼 있다(사례 정리 글, 관련 이슈). 이 글 4번의 GitHub Actions 배포(upload-pages-artifact → deploy-pages)는 Jekyll 빌드를 거치지 않으므로 이 문제가 해당하지 않는다(발행 소스 설정 문서, 커스텀 워크플로 문서). 원인이 다르므로 아래 자주 묻는 질문에서 구분해 둔다

자주 묻는 질문

site·base를 맞게 고쳤는데도 CSS·JS가 여전히 404다.

브랜치 배포(빌드 결과를 gh-pages 브랜치 등에 커밋해 그 브랜치를 발행 소스로 쓰는 방식)를 쓰고 있다면 Jekyll이 _astro 폴더를 통째로 무시하고 있을 가능성이 있다. GitHub Pages는 발행 소스를 브랜치로 선택하면 기본적으로 배포 콘텐츠를 Jekyll로 처리하는데, Jekyll은 언더스코어로 시작하는 폴더·파일을 빌드 결과에서 제외한다(GitHub Pages·Jekyll 문서). 이 경우는 base가 아니라 파일 자체가 배포되지 않는 것이 원인이라 site·base를 아무리 고쳐도 해결되지 않는다. 배포 결과에 .nojekyll이라는 빈 파일을 두면 Jekyll 처리를 건너뛴다(사례 정리 글).

반면 이 글 4번에서 다룬 GitHub Actions 배포(upload-pages-artifact → deploy-pages)는 워크플로가 빌드 산출물을 아티팩트로 직접 올리는 방식이라 Jekyll 빌드 단계를 워크플로에 명시적으로 추가하지 않는 한 Jekyll이 개입하지 않는다. GitHub Docs는 발행 소스를 “브랜치에서 배포”로 두면 사이트가 자동으로 게시되고 “GitHub Actions”로 두면 워크플로가 트리거될 때 게시된다고 구분하며(발행 소스 설정 문서), 커스텀 워크플로 문서의 예시에서도 Jekyll 빌드는 actions/jekyll-build-pages 단계를 별도로 넣었을 때만 실행된다(커스텀 워크플로 문서). 즉 이 글의 4번 워크플로처럼 Jekyll 빌드 단계 없이 upload-pages-artifact로 바로 아티팩트를 올리는 구성이라면 _astro 폴더가 그대로 배포되므로, .nojekyll을 추가할 필요가 없다.

사용자·조직 사이트(<사용자명>.github.io)에서도 base가 필요한가?

필요 없다. 이 저장소는 도메인 루트(https://<사용자명>.github.io)에서 서빙되므로 base 기본값 '/'가 실제 배포 경로와 이미 일치한다(GitHub Pages 배포 가이드).

base 값 끝에 슬래시를 붙여야 하나?

공식 가이드의 예시는 base: '/my-repo'처럼 끝에 슬래시를 붙이지 않는다(GitHub Pages 배포 가이드). 최종적으로 BASE_URL에 끝 슬래시가 붙는지는 base 자체가 아니라 trailingSlash 설정이 결정한다(base 설정 문서).

참고 자료