Ir al contenido

Despliega tu proyecto de Astro en GitHub Pages

Puedes usar GitHub Pages para alojar un sitio web de Astro estático y prerenderizado directamente desde un repositorio en GitHub.com usando GitHub Actions.

Cómo desplegar

Sección titulada «Cómo desplegar»

Astro mantiene la acción oficial de Astro para GitHub para desplegar tu proyecto en GitHub Pages con muy poca configuración, y es la forma recomendada de desplegar en GitHub Pages.

Sigue las instrucciones a continuación para usar la GitHub Action y desplegar tu proyecto de Astro en GitHub Pages. Esto creará un sitio web desde tu repositorio en una URL de GitHub (por ejemplo, https://<usuario>.github.io/<mi-repo>). Una vez desplegado, puedes opcionalmente configurar un dominio personalizado para desplegar tu sitio de GitHub Pages en tu dominio preferido (por ejemplo, https://example.com).

  1. Crea un nuevo archivo en tu proyecto en .github/workflows/deploy.yml y pega el siguiente YAML.

    deploy.yml
    name: Deploy to GitHub Pages
    

    on:
      # Activa el flujo de trabajo cada vez que hagas push a la rama `main`
      # Usando un nombre de rama diferente? Reemplaza `main` con el nombre de tu rama
      push:
        branches: [ main ]
      # Te permite ejecutar este flujo de trabajo manualmente desde la pestaña Acciones en GitHub.
      workflow_dispatch:
    

    # Permite que este trabajo clone el repositorio y cree un despliegue de página
    permissions:
      contents: read
      pages: write
      id-token: write
    

    jobs:
      build:
        runs-on: ubuntu-latest
        steps:
          - name: Checkout your repository using git
            uses: actions/checkout@v5
          - name: Install, build, and upload your site
            uses: withastro/action@v5
            # with:
              # path: . # La ubicación raíz de tu proyecto de Astro dentro del repositorio. (opcional)
              # node-version: 24 # La versión específica de Node que debería usarse para construir tu sitio. Por defecto es 22. (opcional)
              # package-manager: pnpm@latest # El gestor de paquetes de Node que debería usarse para instalar dependencias y construir tu sitio. Detectado automáticamente basado en tu lockfile. (opcional)
              # build-cmd: pnpm run build # El comando para compilar tu sitio. Por defecto ejecuta el script/tarea build del paquete. (opcional)
            # env:
              # PUBLIC_POKEAPI: 'https://pokeapi.co/api/v2' # Usa comillas simples para el valor de la variable. (opcional)
    

      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@v4

    La acción de Astro puede configurarse con entradas opcionales. Puedes proporcionarlas descomentando la línea with: y la entrada que deseas usar.

    Si tu sitio requiere variables de entorno públicas, descomenta la línea env: y agrégalas allí. (Consulta la documentación de GitHub sobre cómo configurar secretos para agregar variables de entorno privadas).

  2. En el archivo de configuración de Astro, establece site (EN) con la URL de GitHub de tu sitio desplegado.

    astro.config.mjs
    import { defineConfig } from 'astro/config'
    

    export default defineConfig({
      site: 'https://astronaut.github.io',
    })

    El valor de site debe ser uno de los siguientes:

  3. En astro.config.mjs, configura un valor para base (EN) (generalmente requerido).

    GitHub Pages publicará tu sitio web en una dirección que depende tanto de tu nombre de usuario como del nombre de tu repositorio (por ejemplo, https://<usuario>.github.io/<mi-repo>/). Establece un valor para base que especifique el repositorio de tu sitio web, para que Astro entienda que la raíz de tu sitio es /mi-repo en lugar del / predeterminado. Puedes omitir esto si el nombre de tu repositorio coincide con el patrón especial <usuario>.github.io (por ejemplo, https://github.com/usuario/usuario.github.io/).

    Configura base como el nombre del repositorio comenzando con una barra diagonal (por ejemplo, /mi-repo):

    astro.config.mjs
    import { defineConfig } from 'astro/config'
    

    export default defineConfig({
      site: 'https://astronaut.github.io',
      base: '/mi-repo',
    })

  4. En GitHub, ve a la pestaña Settings de tu repositorio y busca la sección Pages dentro de la configuración.

  5. Elige GitHub Actions como la fuente de tu sitio.

Cuando hagas push de cambios en el repositorio de tu proyecto de Astro, la GitHub Action los desplegará automáticamente en tu URL de GitHub.

Cambia tu URL de GitHub por un dominio personalizado

Sección titulada «Cambia tu URL de GitHub por un dominio personalizado»

Una vez que tu proyecto de Astro esté desplegado en GitHub Pages en una URL de GitHub siguiendo las instrucciones anteriores, puedes configurar un dominio personalizado. Esto significa que los usuarios podrán visitar tu sitio en tu dominio personalizado https://example.com en lugar de https://<usuario>.github.io.

  1. Configura el DNS en tu proveedor de dominio.

  2. Añade un archivo ./public/CNAME a tu proyecto.

    Crea el siguiente archivo en tu carpeta public/ con una sola línea de texto que especifique tu dominio personalizado:

    public/CNAME
    sub.example.com

    Esto desplegará tu sitio en tu dominio personalizado en lugar de usuario.github.io.

  3. En tu configuración de Astro, actualiza el valor de site con tu dominio personalizado. No establezcas un valor para base, y elimínalo si existe:

    astro.config.mjs
    import { defineConfig } from 'astro/config'
    

    export default defineConfig({
      site: 'https://example.com',
      base: '/mi-repo'
    })

  4. Si es necesario, actualiza todos los enlaces internos de tus páginas para eliminar el prefijo base:

    <a href="/mi-repo/acerca">Acerca</a>

Ejemplos

Sección titulada «Ejemplos»

Más guías de implementación

Contribuir Comunidad Patrocinador