Solução de erros 404 para sites do GitHub Pages

Este guia ajudará você a solucionar problemas comuns que acarretam em um erro 404.

Quem pode usar esse recurso?

O GitHub Pages está disponível em repositórios públicos com o GitHub Free e o GitHub Free para organizações, e em repositórios públicos e privados com o GitHub Pro, o GitHub Team, o GitHub Enterprise Cloud e o GitHub Enterprise Server. Para mais informações, confira "Planos do GitHub".

O GitHub Pages agora usa o GitHub Actions para executar a compilação Jekyll. Ao usar uma ramificação como a origem da sua compilação, o GitHub Actions deverá estar habilitado em seu repositório se você quiser usar o fluxo de trabalho interno do Jekyll. Como alternativa, se o GitHub Actions não estiver disponível ou estiver desabilitado, adicionar um .nojekyll arquivo à raiz da ramificação de origem ignorará o processo de compilação do Jekyll e implantará o conteúdo diretamente. Para mais informações sobre ativar o GitHub Actions, confira "Gerenciando as configurações do GitHub Actions para um repositório".

Solução de erros 404

Neste guia, veja algumas causas comuns para a exibição de um erro 404 durante a criação de um site do GitHub Pages.

Página de status do GitHub

Se um erro 404 for exibido durante a criação de um site do GitHub Pages, verifique primeiro se a Página de status do GitHub contém algum incidente ativo.

Configuração de DNS

Verifique se os registros DNS do GitHub estão configurados corretamente com o provedor DNS. Para saber mais, confira Gerenciar um domínio personalizado do seu site do GitHub Pages.

Cache do navegador

Quando o site do GitHub Pages é privado e um erro 404 é exibido, pode ser necessário limpar o cache do navegador. Para obter mais informações sobre limpeza do cache, consulte a documentação do navegador.

Arquivo index.html

O GitHub Pages procurará um arquivo index.html como o arquivo de entrada para o site.

  • Tenha um arquivo index.html no repositório do site no GitHub. Para saber mais, confira Criar um site do GitHub Pages.

  • O arquivo de entrada deve estar no nível superior da fonte de publicação escolhida. Por exemplo, se a fonte de publicação for o diretório /docs do branch main, o arquivo de entrada deverá estar no diretório /docs de um branch chamado main.

    Se a fonte de publicação for um branch e um diretório, o arquivo de entrada deverá estar no nível superior do diretório de origem no branch de origem. Por exemplo, se a fonte de publicação for o diretório /docs do branch main, o arquivo de entrada deverá estar no diretório /docs de um branch chamado main.

    Se a fonte de publicação for um fluxo de trabalho do GitHub Actions, o artefato que você implantar precisará incluir o arquivo de entrada na parte superior do artefato. Em vez de adicionar o arquivo de entrada ao repositório, há a opção de fazer com que o fluxo de trabalho do GitHub Actions gere esse arquivo de entrada ao ser executado.

  • O nome do arquivo index.html diferencia maiúsculas de minúsculas. Por exemplo, Index.html não funcionará.

  • O nome do arquivo deve ser index.html, não index.HTML ou qualquer outra variação.

Conteúdo do diretório

Verifique se o conteúdo do diretório está no diretório raiz.

Domínio personalizado

Se você estiver usando um domínio personalizado, verifique se ele está configurado corretamente. Para saber mais, confira Sobre domínios personalizados e GitHub Pages.

  • O registro CNAME deve sempre apontar para <USER>.github.io ou <ORGANIZATION>.github.io, excluindo o nome do repositório. Para obter mais informações sobre como criar o registro correto, consulte a documentação do provedor do DNS.
  • Quando você acessa a página de destino, mas encontra links desfeitos, é provável que tenha um nome de domínio personalizado anterior ou esteja revertendo o uso de um nome de domínio personalizado. Nesses casos, alterar o caminho de roteamento não inicia uma reconstrução da página. A solução recomendada é garantir que o site seja reconstruído automaticamente ao adicionar ou remover um nome de domínio personalizado. Isso pode envolver a configuração de um autor de commit e a modificação das configurações de nome de domínio personalizado.

Repositório

Verifique se o repositório atende aos requisitos a seguir.

  • O branch que você está usando para publicar o site deve ser main ou o branch padrão.
  • O repositório deve ter um commit enviado a ele por alguém com as respectivas permissões de administrador, como o proprietário do repositório.
  • Mudar a visibilidade do repositório de público para privado ou vice-versa mudará a URL do site do GitHub Pages, o que resulta em links desfeitos até a reconstrução do site.
  • Se você estiver usando um repositório privado para o site GitHub Pages, verifique se sua assinatura do GitHub Pro, GitHub Team ou GitHub Enterprise Cloud ainda está ativa. Se você renovar o plano, o site GitHub Pages será reimplantado automaticamente. Caso contrário, você poderá alterar a visibilidade do seu repositório para público a fim de continuar usando o GitHub Pages gratuitamente.

Se o erro 404 continuar sendo exibido, inicie uma discussão da GitHub Community na categoria Pages.