Solución de errores 404 en sitios de GitHub Pages

Esta guía te ayudará a solucionar los motivos comunes por los que puede aparecer un error 404.

¿Quién puede utilizar esta característica?

GitHub Pages is available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub’s plans.

GitHub Pages now uses GitHub Actions to execute the Jekyll build. When using a branch as the source of your build, GitHub Actions must be enabled in your repository if you want to use the built-in Jekyll workflow. Alternatively, if GitHub Actions is unavailable or disabled, adding a .nojekyll file to the root of your source branch will bypass the Jekyll build process and deploy the content directly. For more information on enabling GitHub Actions, see Managing GitHub Actions settings for a repository.

Solución de errores 404

En esta guía encontrarás varias razones comunes por las que puede que veas un error 404 al compilar el sitio GitHub Pages.

Página Estado de GitHub

Si ves un error 404 al compilar un sitio GitHub Pages, lo primero que debes hacer es comprobar la página Estado de GitHub para saber si hay incidentes activos.

Configuración de DNS

Asegúrate de que los registros DNS de GitHub se han configurados correctamente con el proveedor de DNS. Para más información, consulta Configurar un dominio personalizado para tu sitio de Páginas de GitHub.

Caché del navegador

Si el sitio GitHub Pages es privados y ves un error 404, es posible que tengas que borrar la caché del explorador. Para obtener más información acerca de limpiar tu caché, consulta la documentación de tu navegador.

Archivo index.html

GitHub Pages buscará un archivo index.html como archivo de entrada para el sitio.

  • Asegúrate de tener un archivo index.html en el repositorio del sitio en GitHub. Para más información, consulta Crear un sitio de Páginas de GitHub.

  • El archivo de entrada debe estar en el nivel superior del origen de publicación elegido. Por ejemplo, si el origen de publicación es el directorio /docs de la rama main, el archivo de entrada debe estar en el directorio /docs de una rama denominada main.

    Si el origen de publicación es una rama y un directorio, el archivo de entrada debe estar en el nivel superior del directorio de origen de la rama de origen. Por ejemplo, si el origen de publicación es el directorio /docs de la rama main, el archivo de entrada debe estar en el directorio /docs de una rama denominada main.

    Si la fuente de publicación es un flujo de trabajo de GitHub Actions, el artefacto que implementes debe incluir el archivo de entrada en el nivel superior del artefacto. En lugar de agregar el archivo de entrada al repositorio, puedes decidir que el flujo de trabajo de GitHub Actions genere el archivo de entrada cuando se ejecute el flujo de trabajo.

  • El nombre del archivo index.html distingue mayúsculas de minúsculas. Por ejemplo, Index.html no funcionará.

  • El nombre del archivo debe ser index.html, no index.HTML, ni otra variación del mismo.

Contenido del directorio

Comprueba que el contenido del directorio se encuentra en el directorio raíz.

Dominio personalizado

Si usas un dominio personalizado, asegúrate de que está configurado correctamente. Para más información, consulta Acerca de los dominios personalizados y las Páginas de GitHub.

  • El registro CNAME siempre debe apuntar a <USER>.github.io o <ORGANIZATION>.github.io, excepto el nombre del repositorio. Para obtener más información acerca de cómo crear el registro correcto, consulta la documentación de tu proveedor de DNS.
  • Si puedes acceder a la página de aterrizaje, pero encuentras vínculos rotos, es probable que se deba que no tenías un nombre de dominio personalizado o que estás revirtiendo el proceso de tener un nombre de dominio personalizado. En tales casos, el mero hecho de cambiar la ruta de acceso de enrutamiento no inicia una regeneración de la página. La solución recomendada es asegurarse de que el sitio se vuelve a generar automáticamente al agregar o quitar un nombre de dominio personalizado, lo que puede implicar la configuración de un autor de confirmación y la modificación de la configuración del nombre de dominio personalizado.

Repositorio

Comprueba si el repositorio cumple los siguientes requisitos.

  • La rama que uses para publicar el sitio debe ser main o la rama predeterminada.
  • El repositorio debe tener una confirmación insertada por alguien con permisos de administrador en el mismo, como su propietario.
  • Cambiar la visibilidad del repositorio de público a privado o viceversa cambiará la dirección URL del sitio GitHub Pages, lo que dará lugar a vínculos rotos hasta que se vuelva a generar el sitio.
  • Si usa un repositorio privado para el sitio de GitHub Pages, compruebe si la suscripción a GitHub Pro, GitHub Team o GitHub Enterprise Cloud aún están activas. Si renueva el plan, el sitio de GitHub Pages se volverá a implementar automáticamente. De lo contrario, puede cambiar la visibilidad del repositorio a público para seguir usando GitHub Pages de forma gratuita.

Si sigues recibiendo un error 404, inicia una discusión de GitHub Community en la categoría Pages.