GitHub Pages 404 오류 해결 방법｜github.io 배포 후 페이지가 안 뜰 때 확인할 7가지

GITHUB PAGES · TROUBLESHOOTING

GitHub Pages 배포 후 404 오류가 발생한다면?

index.html 위치부터 Pages 설정, 배포 상태, URL 경로까지 초보자도 순서대로 확인할 수 있도록 정리했습니다.

GitHub Pages는 별도의 웹호스팅 비용 없이 정적 웹사이트를 공개할 수 있는 편리한 서비스입니다.

하지만 GitHub에 HTML 파일을 업로드하고 Pages 설정까지 마쳤는데도 사이트에 접속하면 404 오류가 표시되는 경우가 있습니다.

이때는 무작정 저장소를 삭제하고 다시 만들기보다 몇 가지 항목을 순서대로 확인하는 것이 좋습니다.

이번 글에서는 GitHub 공식 문서를 바탕으로 GitHub Pages 404 오류가 발생했을 때 확인할 7가지 항목을 정리하겠습니다.

먼저 확인하세요
GitHub Pages를 처음 설정하는 경우라면 배포 방법을 먼저 확인한 다음 이 글을 참고하는 것이 좋습니다.

관련 글 : 깃허브(GitHub)로 웹사이트 무료 배포하기
※ https://time-memorizer.tistory.com/212

깃허브(github)로 웹사이트 무료 배포하기(github.io)

 

1. GitHub Pages 404 오류가 발생하는 이유

HTTP 404는 요청한 주소에 해당하는 리소스를 찾을 수 없다는 의미입니다.

GitHub Pages에서 404가 발생한다면 다음과 같은 상황을 먼저 의심해 볼 수 있습니다.

증상	확인할 항목
사이트 첫 화면이 404	index.html 위치 및 파일명
배포 자체가 안 됨	Pages 게시 설정 및 Actions 실행 결과
특정 주소에서만 404	저장소 이름 및 URL 경로
커스텀 도메인에서만 오류	도메인 및 DNS 설정
배포 후 일부 파일만 오류	파일 경로 및 대소문자

모든 404 오류가 같은 원인으로 발생하는 것은 아닙니다. 따라서 사이트 전체가 열리지 않는지, 특정 페이지만 열리지 않는지 먼저 구분하는 것이 중요합니다.

2. index.html 파일 위치 확인하기

가장 먼저 확인할 항목은 index.html 파일의 위치입니다.

GitHub Pages는 일반적인 HTML 사이트에서 index.html 파일을 시작 페이지로 사용합니다.

이 파일은 선택한 게시 원본의 최상위 위치에 있어야 합니다.

정상적인 폴더 구조 예시

my-website/
├── index.html
├── css/
│   └── style.css
├── js/
│   └── main.js
└── images/
    └── logo.png

위 구조에서 GitHub Pages 게시 원본이 main 브랜치의 /(root)라면 index.html 파일을 정상적으로 찾을 수 있습니다.

확인이 필요한 구조

my-website/
└── website/
    └── index.html

게시 원본이 저장소의 루트로 설정되어 있다면 위와 같은 구조에서는 시작 파일을 찾지 못할 수 있습니다.

이 경우 index.html을 게시 원본의 최상위 위치로 옮기거나, 프로젝트 구조에 맞게 배포 방식을 변경해야 합니다.

KEY POINT
index.html은 저장소 어디에나 있으면 되는 것이 아니라 GitHub Pages가 게시하도록 설정된 위치에 있어야 합니다.

3. index.html 파일명 대소문자 확인하기

파일 위치가 맞다면 다음으로 파일명의 대소문자를 확인해 보세요.

GitHub Pages에서는 파일명의 대소문자를 구분합니다.

올바른 파일명
index.html

확인이 필요한 파일명
Index.html
INDEX.HTML
index.HTML

특히 Windows 환경에서는 파일명의 대소문자를 크게 의식하지 않고 작업하는 경우가 있습니다.

로컬 환경에서 정상적으로 열리던 페이지라도 배포 환경에서는 파일명 차이로 문제가 발생할 수 있으므로 정확히 확인하는 것이 좋습니다.

4. GitHub Pages 게시 설정 확인하기

파일에 문제가 없다면 GitHub Pages가 어느 브랜치와 폴더를 게시하도록 설정되어 있는지 확인해야 합니다.

설정 확인 순서

GITHUB REPOSITORY

Repository
↓
Settings
↓
Pages
↓
Build and deployment

Source 항목에서 게시 방식을 확인합니다.

일반적인 정적 HTML 사이트라면 다음과 같이 설정할 수 있습니다.

Source : Deploy from a branch

Branch : main

Folder : /(root)

위 설정은 예시입니다. 실제 파일이 /docs 폴더에 있다면 해당 폴더를 게시 원본으로 선택할 수도 있습니다.

반면 React나 Vite처럼 빌드 과정이 필요한 프로젝트는 GitHub Actions를 이용해 빌드 결과물을 게시하는 방식이 적합할 수 있습니다.

KEY POINT
저장소의 파일 위치와 Pages에 설정된 게시 원본이 일치해야 합니다.

5. github.io 주소가 올바른지 확인하기

GitHub Pages는 사이트 유형에 따라 접속 주소가 달라집니다.

특히 사용자 사이트와 프로젝트 사이트를 혼동하면 잘못된 주소로 접속하게 될 수 있습니다.

사용자 사이트

https://username.github.io/

사용자 사이트는 일반적으로 username.github.io라는 이름의 저장소를 사용합니다.

프로젝트 사이트

https://username.github.io/project-name/

프로젝트 사이트는 일반적으로 사용자 주소 뒤에 저장소 이름이 추가됩니다.

예를 들어 저장소 이름이 my-website라면 기본 접속 주소는 다음과 같습니다.

https://username.github.io/my-website/

프로젝트 사이트인데 https://username.github.io/로만 접속하고 있다면 주소를 다시 확인해 보세요.

※ 위 주소는 사용자 지정 도메인을 설정하지 않은 경우의 기본 URL 예시입니다.

6. GitHub Actions 배포 상태 확인하기

파일과 Pages 설정이 정상인데도 사이트가 열리지 않는다면 배포 과정에서 오류가 발생했는지 확인해야 합니다.

GitHub Pages는 배포 과정에서 GitHub Actions 워크플로를 사용합니다.

확인 방법

Repository → Actions

최근 Pages 관련 워크플로 실행 결과를 확인합니다.

실행 결과가 성공이라면 배포된 사이트 주소를 확인하고, 실패했다면 해당 워크플로를 열어 어떤 단계에서 오류가 발생했는지 확인해야 합니다.

특히 빌드 과정이 있는 프로젝트라면 빌드 결과물에 실제 시작 파일이 포함되어 있는지도 중요합니다.

GitHub Actions를 이용해 게시하는 경우에는 배포 아티팩트의 최상위 위치에 시작 파일이 포함되어 있어야 합니다.

KEY POINT
GitHub에 파일을 업로드했다고 해서 배포가 반드시 성공한 것은 아닙니다.
Actions 실행 결과까지 확인하는 것이 좋습니다.

7. 저장소 공개 여부와 커스텀 도메인 확인하기

마지막으로 저장소의 공개 설정과 사용자 지정 도메인 설정을 확인해 보세요.

저장소 공개 여부

GitHub Free에서는 일반적으로 공개 저장소를 이용해 GitHub Pages를 게시할 수 있습니다.

비공개 저장소를 사용하고 있다면 계정 요금제와 저장소의 Pages 지원 조건을 확인해야 합니다.

또한 저장소의 공개 여부를 변경했다면 기존 사이트 주소와 배포 상태도 다시 확인하는 것이 좋습니다.

커스텀 도메인 설정

별도로 구매한 도메인을 GitHub Pages에 연결했다면 DNS 설정이 올바른지 확인해야 합니다.

특히 서브도메인을 CNAME으로 연결하는 경우 대상 주소에 저장소 경로를 포함하지 않도록 주의해야 합니다.

예시

www.example.com

CNAME → username.github.io

DNS 설정 변경은 즉시 반영되지 않을 수 있습니다. GitHub 공식 문서에서는 DNS 변경 사항이 전파되는 데 최대 24시간이 걸릴 수 있다고 안내합니다.

커스텀 도메인을 사용하지 않는다면 이 항목은 건너뛰어도 됩니다.

8. 첫 화면은 열리는데 CSS나 이미지가 안 나온다면?

이 경우는 사이트 전체가 404인 상황과 구분해야 합니다.

HTML 첫 화면은 정상적으로 열리는데 CSS나 JavaScript, 이미지 파일만 표시되지 않는다면 리소스 경로 문제일 가능성이 있습니다.

예를 들어 프로젝트 사이트가 다음 주소에 배포되었다고 가정해 보겠습니다.

https://username.github.io/my-website/

이때 HTML에 다음과 같이 작성했다면

<link rel="stylesheet" href="/css/style.css">

브라우저는 일반적으로 도메인의 루트 경로인 https://username.github.io/css/style.css를 요청합니다.

하지만 실제 파일이 프로젝트 폴더 아래에 있다면 해당 요청은 404가 발생할 수 있습니다.

이 경우 현재 HTML 파일을 기준으로 하는 상대경로를 사용할 수 있습니다.

<link rel="stylesheet" href="./css/style.css">

단, 상대경로는 현재 문서의 URL과 실제 폴더 구조에 따라 달라지므로 모든 페이지에서 동일하게 적용할 수 있는 해결책은 아닙니다.

브라우저 개발자 도구의 Network 탭에서 실제로 어떤 파일 URL이 404를 반환하는지 확인하면 문제를 더 정확하게 찾을 수 있습니다.

테스트로 css 경로에 파일명을 다르게 써서 접근시 해당 파일을 찾을수 없어 404 에러가 뜨는 상황 확인

9. GitHub Pages 404 오류 최종 체크리스트

지금까지 확인한 내용을 정리하면 다음과 같습니다.

FINAL CHECKLIST

□ 게시 원본에 index.html이 있는가?

□ 파일명이 정확히 index.html인가?

□ Settings → Pages의 Source가 올바른가?

□ Branch와 Folder 설정이 실제 파일 위치와 일치하는가?

□ github.io 접속 주소가 정확한가?

□ Actions에서 배포가 성공했는가?

□ 저장소 공개 여부와 계정 조건이 적절한가?

□ 커스텀 도메인을 사용한다면 DNS가 올바른가?

□ CSS·이미지 파일의 경로가 정확한가?

특히 GitHub Pages를 처음 사용하는 경우라면 다음 세 가지부터 확인하는 것을 추천합니다.

ONE-LINE SUMMARY

index.html 위치 확인
↓
Settings → Pages 설정 확인
↓
Actions 배포 성공 여부 확인

이 세 가지를 확인한 뒤에도 문제가 해결되지 않는다면 접속 URL과 도메인 설정, 파일 경로 등을 추가로 점검해 보세요.

10. 참고한 공식 문서

이 글은 GitHub의 공식 문서를 참고해 작성한 문제 해결 가이드입니다.

특정 오류를 직접 경험하고 해결한 후기라기보다는 GitHub Pages에서 404가 발생했을 때 확인할 수 있는 주요 설정과 점검 방법을 정리한 자료입니다.

GitHub Docs — 404 오류 문제 해결
GitHub Pages에서 발생하는 일반적인 404 오류 원인

GitHub Docs — 게시 원본 구성
Branch, Folder, GitHub Actions 게시 설정

GitHub Docs — 커스텀 도메인 관리
도메인 연결과 DNS 설정

마무리

GitHub Pages에서 404 오류가 발생했다고 해서 반드시 복잡한 문제가 있는 것은 아닙니다.

게시 원본에 시작 파일이 없거나, Pages 설정과 실제 폴더 구조가 일치하지 않거나, 잘못된 URL로 접속하는 경우에도 문제가 발생할 수 있습니다.

중요한 것은 무작정 설정을 변경하기보다 현재 어떤 단계에서 문제가 발생했는지 구분하고 순서대로 확인하는 것입니다.

RELATED CONTENT

GitHub Pages를 처음 사용한다면?

GitHub 저장소 생성부터 무료 웹사이트 배포까지 기본적인 과정을 먼저 살펴보세요.

깃허브(GitHub)로 웹사이트 무료 배포하기 →

※ https://time-memorizer.tistory.com/212

깃허브(github)로 웹사이트 무료 배포하기(github.io)