GitHub 페이지 사이트에 대한 404 오류 문제 해결

이 가이드는 404 오류가 표시되는 일반적인 이유를 해결하는 데 도움이 됩니다.

누가 이 기능을 사용할 수 있나요?

GitHub Pages은(는) 조직의 GitHub Free 및 GitHub Free이(가) 있는 퍼블릭 리포지토리와 GitHub Pro, GitHub Team, GitHub Enterprise Cloud 및 GitHub Enterprise Server의 퍼블릭 및 프라이빗 리포지토리에서 사용할 수 있습니다. 자세한 내용은 “GitHub의 플랜”를 참조하세요.

GitHub Pages은(는) 이제 GitHub Actions을(를) 사용하여 Jekyll 빌드를 실행합니다. 빌드의 원본으로 분기를 사용하는 경우 기본 제공 Jekyll 워크플로를 사용하려면 리포지토리에서 GitHub Actions을(를) 사용하도록 설정해야 합니다. 또는 GitHub Actions을(를) 사용할 수 없거나 사용하지 않도록 설정한 경우 원본 분기의 루트에 .nojekyll 파일을 추가하면 Jekyll 빌드 프로세스를 무시하고 콘텐츠를 직접 배포합니다. GitHub Actions 사용에 대한 자세한 내용은 "리포지토리에 대한 GitHub Actions 설정 관리"을 참조하세요.

404 오류 해결

이 가이드에서는 GitHub Pages 사이트를 빌드하는 동안 404 오류가 발생할 수 있는 일반적인 이유를 확인할 수 있습니다.

GitHub의 상태 페이지

GitHub Pages 사이트를 빌드하는 동안 404 오류가 표시되면 먼저 활성 인시던트에 대한 GitHub의 상태 페이지를 확인합니다.

DNS 설정

GitHub의 DNS 레코드가 DNS 공급자에 올바르게 설정되어 있는지 확인합니다. 자세한 내용은 "GitHub Pages 사이트의 사용자 지정 도메인 관리"을(를) 참조하세요.

브라우저 캐시

GitHub Pages 사이트가 비공개이고 404 오류가 표시되는 경우 브라우저의 캐시를 지워야 할 수 있습니다. 캐시 지우기에 관한 자세한 내용은 브라우저의 설명서를 참조하세요.

index.html 파일

GitHub Pages은(는) 사이트에 대한 항목 파일로 index.html 파일을 찾습니다.

  • GitHub Enterprise Cloud에 있는 사이트의 리포지토리에 index.html 파일이 있는지 확인합니다. 자세한 내용은 "GitHub Pages 사이트 만들기"을(를) 참조하세요.

  • 항목 파일은 선택한 게시 원본의 최상위 수준에 있어야 합니다. 예를 들어 게시 원본이 main 분기의 /docs 디렉터리인 경우, 항목 파일은 main이라는 분기의 /docs 디렉터리에 있어야 합니다.

    게시 원본이 분기 및 디렉터리인 경우 항목 파일은 원본 분기의 소스 디렉터리 최상위 수준에 있어야 합니다. 예를 들어 게시 원본이 main 분기의 /docs 디렉터리인 경우, 항목 파일은 main이라는 분기의 /docs 디렉터리에 있어야 합니다.

    게시 원본이 GitHub Actions 워크플로인 경우 배포하는 아티팩트에 아티팩트 최상위 수준에 있는 항목 파일이 포함되어야 합니다. 항목 파일을 리포지토리에 추가하는 대신 워크플로가 실행되면 GitHub Actions 워크플로에서 항목 파일을 생성하도록 선택할 수 있습니다.

  • index.html 파일 이름은 대/소문자를 구분합니다. 예를 들어 Index.html은 작동하지 않습니다.

  • 파일의 이름은 index.HTML 또는 다른 변형이 아닌 index.html이어야 합니다.

디렉터리 콘텐츠

디렉터리 콘텐츠가 루트 디렉터리에 있는지 확인합니다.

사용자 지정 도메인

사용자 지정 도메인을 사용하는 경우 올바르게 설정되었는지 확인합니다. 자세한 내용은 "사용자 지정 도메인 및 GitHub Pages 정보"을(를) 참조하세요.

  • CNAME 레코드는 리포지토리 이름을 제외하고 항상 <USER>.github.io 또는 <ORGANIZATION>.github.io를 가리킵니다. 올바른 레코드를 만드는 방법에 대한 자세한 내용은 DNS 공급자의 설명서를 참조하세요.
  • 방문 페이지에 액세스할 수 있지만 전체 링크가 끊어진 경우 이전에 사용자 지정 도메인 이름이 없거나 사용자 지정 도메인 이름에서 되돌리고 있기 때문일 수 있습니다. 이러한 경우 라우팅 경로를 변경해도 페이지 다시 빌드가 시작되지 않습니다. 권장되는 해결 방법은 사용자 지정 도메인 이름을 추가하거나 제거할 때 사이트가 자동으로 다시 빌드되도록 하는 것입니다. 여기에는 커밋 작성자를 구성하고 사용자 지정 도메인 이름 설정을 수정하는 작업이 포함될 수 있습니다.

리포지토리

리포지토리가 다음 요구 사항을 충족하는지 확인합니다.

  • 사이트를 게시하는 데 사용하는 분기가 main 또는 기본 분기입니다.
  • 리포지토리에 대한 관리자 권한이 있는 사용자(예: 리포지토리 소유자)가 리포지토리에 커밋을 푸시해야 합니다.
  • 리포지토리의 표시 여부를 공개에서 비공개로 전환하거나 그 반대로 전환하면 GitHub Pages 사이트의 URL이 변경되므로 사이트가 다시 빌드될 때까지 링크가 끊어집니다.
  • GitHub Pages 사이트에 프라이빗 리포지토리를 사용하는 경우 GitHub Pro, GitHub Team, GitHub Enterprise Cloud 구독이 여전히 활성 상태인지 확인하세요. 플랜을 갱신하면 GitHub Pages 사이트가 자동으로 다시 배포됩니다. 갱신하지 않을 시 리포지토리의 표시 유형을 공용으로 변경하여 GitHub Pages을(를) 무료로 계속 사용할 수 있습니다.

여전히 404 오류가 발생하는 경우 Pages 범주에서 GitHub Community 토론을 시작하세요.