콘텐츠로 이동

Astro 사이트를 Github Pages에 배포하세요

GitHub Pages를 사용하면 GitHub Actions를 사용하여 GitHub.com의 리포지토리에서 직접 미리 렌더링된 정적 Astro 웹사이트를 호스팅할 수 있습니다.

배포 방법

섹션 제목: “배포 방법”

Astro는 아주 적은 구성으로 프로젝트를 GitHub Pages에 배포할 수 있는 공식 Astro GitHub Action을 유지 관리하며, 이는 권장되는 배포 방법입니다.

아래 지침에 따라 GitHub Action을 사용하여 Astro 사이트를 GitHub Pages에 배포하세요. 이렇게 하면 GitHub URL (예: https://<username>.github.io/<my-repo>)의 리포지토리에서 웹사이트가 만들어집니다. 배포가 완료되면 선택적으로 사용자 정의 도메인을 구성하여 원하는 도메인 (예: https://example.com)에 GitHub Pages 사이트를 배포할 수 있습니다.

  1. 프로젝트의 .github/workflows/deploy.yml에 새 파일을 만들고 아래 YAML에 붙여넣습니다.

    deploy.yml
    name: Deploy to GitHub Pages
    

    on:
      # 'main' 브랜치로 푸시할 때마다 워크플로를 트리거합니다.
      # 다른 브랜치 이름을 사용하시나요? `main`을 브랜치 이름으로 바꾸세요.
      push:
        branches: [ main ]
      # GitHub의 Actions 탭에서 이 워크플로를 수동으로 실행할 수 있습니다.
      workflow_dispatch:
    

    # 이 작업이 리포지토리를 복제하고 페이지 배포를 생성하도록 허용합니다.
    permissions:
      contents: read
      pages: write
      id-token: write
    

    jobs:
      build:
        runs-on: ubuntu-latest
        steps:
          - name: Checkout your repository using git
            uses: actions/checkout@v4
          - name: Install, build, and upload your site
            uses: withastro/action@v3
            # with:
              # path: . # 저장소 내 Astro 프로젝트의 루트 위치입니다. (선택 사항)
              # node-version: 20 # 사이트를 빌드하는 데 사용해야 하는 특정 버전의 Node입니다. 기본값은 20입니다. (선택 사항)
              # package-manager: pnpm@latest # 종속성을 설치하고 사이트를 빌드하는 데 사용해야 하는 노드 패키지 관리자입니다. lockfile을 기반으로 자동으로 감지됩니다. (선택 사항)
            # env:
              # PUBLIC_POKEAPI: 'https://pokeapi.co/api/v2' # 변수 값에는 작은따옴표를 사용합니다. (선택 사항)
    

      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

    선택적 입력으로 Astro 액션을 구성할 수 있습니다. 사용하려는 입력과 with: 줄의 주석을 해제하여 입력값을 제공하세요.

    사이트에 공개 환경 변수가 필요한 경우 env: 줄의 주석을 해제하고 여기에 값을 추가하세요. (비공개 환경 변수를 추가하는 방법은 비밀 설정에 대한 GitHub 문서를 참조하세요.)

  2. Astro 구성 파일에서 site를 배포한 사이트의 GitHub URL로 설정합니다.

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

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

    site 값은 다음 중 하나여야 합니다.

    • 사용자 이름을 기반으로 하는 URL: https://<username>.github.io
    • GitHub 조직의 비공개 페이지에 사용할 수 있는 자동 생성된 임의의 URL: https://<random-string>.pages.github.io/

  3. astro.config.mjs에서 base 값을 구성합니다. (일반적으로 필수)

    GitHub Pages는 사용자 이름과 리포지토리 이름에 따라 달라지는 주소 (예: https://<username>/github.io/<my-repo>/)에 웹사이트를 게시합니다. 웹사이트의 리포지토리를 지정하는 base 값을 설정합니다. 이는 Astro에게 웹사이트의 루트가 기본값인 /가 아닌 /my-repo임을 알려주기 위한 것입니다. 리포지토리 이름이 <username>.github.io 패턴 (예: https://github.com/username/username.github.io/)과 일치하는 경우 이 단계를 건너뛸 수 있습니다.

    base를 슬래시 (예: /my-repo)로 시작하는 리포지토리의 이름으로 구성합니다.

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

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

  4. GitHub에서 리포지토리의 Settings 탭으로 이동하여 Pages 섹션을 찾습니다.

  5. 사이트의 Source로 GitHub Actions를 선택합니다.

Astro 프로젝트의 리포지토리에 변경 사항을 푸시하면 GitHub Action이 자동으로 GitHub URL에 배포합니다.

Github URL을 사용자 정의 도메인으로 변경하기

섹션 제목: “Github URL을 사용자 정의 도메인으로 변경하기”

이전 지침에 따라 Astro 프로젝트가 GitHub URL의 GitHub Pages에 배포되면 사용자 정의 도메인을 구성할 수 있습니다. 즉, 사용자는 https://<username>.github.io 대신 사용자 정의 도메인인 https://example.com에서 사이트를 방문할 수 있습니다.

  1. 도메인 공급업체의 DNS를 구성합니다.

  2. 프로젝트에 ./public/CNAME 레코드를 추가합니다.

    public/ 폴더에 사용자 정의 도메인을 지정하는 한 줄의 텍스트가 포함된 다음 파일을 만듭니다.

    public/CNAME
    sub.example.com

    이렇게 하면 user.github.io 대신 사용자 정의 도메인에 사이트를 배포합니다.

  3. Astro 구성에서 site 값을 사용자 정의 도메인으로 업데이트합니다. base 값은 설정하지 말고, 이미 존재한다면 제거하세요.

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

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

  4. 필요한 경우 모든 페이지 내부 링크를 업데이트하여 base 접두사를 제거합니다.

    <a href="/my-repo/about">About</a>

예시

섹션 제목: “예시”

더 많은 배포 가이드

기여하기 커뮤니티 후원하기