GitHub Pages 배포 실패 및 해결 과정 정리

🆘 Issue: GitHub Actions를 이용한 Vite + Vue3 프로젝트의 GitHub Pages 배포 실패

---

🐛 1. 문제 상황

GitHub Actions를 이용해 Vite 기반 Vue3 프로젝트를 GitHub Pages에 배포하려 했으나, 배포가 정상적으로 진행되지 않고 다음과 같은 에러가 발생함.

🔴 발생한 주요 에러

1. 배포 실패 (No uploaded artifact was found!)

   Error: No uploaded artifact was found! Please check if there are any errors at build step, or uploaded artifact name is correct.

   • actions/upload-artifact@v4를 사용해 dist/ 폴더를 업로드했지만,
     이후 deploy-pages@v2에서 해당 artifact를 찾지 못하는 문제 발생.

2. CORS 문제

   Access to script at 'file:///C:/assets/index-DUcDJv4I.js' from origin 'null' has been blocked by CORS policy.

   • 로컬에서 다운로드한 아티팩트를 file:/// 프로토콜을 통해 열었을 때 발생.
   • GitHub Pages 배포가 정상적으로 이루어지지 않았음을 의미.

3. 잘못된 base 경로 설정으로 인해 CSS, JS 파일 로딩 실패

   Failed to load resource: net::ERR_FILE_NOT_FOUND

   • GitHub Pages는 프로젝트명(/blueprint_frontend/)을 포함한 경로를 기본값으로 사용해야 하는데,
     Vite의 base 설정이 잘못되어 정적 파일을 찾지 못함.

---

🔎 2. 해결을 위해 시도한 방법

🔹 1️⃣ dist 폴더가 제대로 생성되고 업로드되는지 확인

• npm run build 이후 dist/ 폴더가 정상적으로 생성되는지 확인.
• GitHub Actions Workflow에 다음을 추가하여 빌드 확인:

  - name: Verify Build Output
    run: ls -R ./dist || echo "dist folder not found!"

• ✅ 결과: dist/ 폴더는 정상적으로 생성되었음.

---

🔹 2️⃣ GitHub Pages에서 사용할 artifact 업로드 방식 변경

• 기존에는 일반적인 actions/upload-artifact@v4를 사용:

  - name: Upload Pages artifact
    uses: actions/upload-artifact@v4
    with:
      name: github-pages
      path: ./dist/

• 그러나 GitHub Pages에서는 upload-artifact@v4가 아닌 upload-pages-artifact@v3를 사용해야 함.
• 🔧 해결 방법:

  - name: Upload artifact
    uses: actions/upload-pages-artifact@v3
    with:
      path: './dist'

• ✅ 결과: 올바르게 Pages용 artifact가 업로드됨.

---

🔹 3️⃣ GitHub Pages 환경에서 자동으로 base 경로 설정

• 기존에는 vite.config.js에서 base 경로를 하드코딩:

  base: process.env.GITHUB_PAGES ? '/blueprint_frontend/' : '/',

• 하지만, GitHub Actions에서는 GITHUB_PAGES 환경 변수가 자동으로 설정되지 않음.
• 🔧 해결 방법:
  actions/configure-pages@v4를 사용하여 GitHub Pages에서 base를 자동 설정.

  - name: Setup Pages
    uses: actions/configure-pages@v4

• ✅ 결과: GitHub Pages 배포 시 base가 자동으로 /blueprint_frontend/로 설정됨.

---

🔹 4️⃣ 배포 후 자동으로 GitHub Pages URL을 출력하도록 수정

• 기존 Workflow에서는 배포 후 페이지 URL을 알 수 없었음.
• 🔧 해결 방법:
  deploy 단계에서 deployment.outputs.page_url을 추가하여 자동으로 배포된 URL을 확인할 수 있도록 수정.

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

• ✅ 결과: 배포가 완료되면 GitHub Actions UI에서 배포된 페이지 URL이 자동으로 제공됨.

---

✅ 3. 최종 해결 방법

1. upload-pages-artifact@v3를 사용하여 GitHub Pages와 호환되는 방식으로 artifact 업로드
2. configure-pages@v4를 추가하여 GitHub Pages 환경에서 base 경로 자동 설정
3. 배포 후 GitHub Pages URL을 자동 출력하도록 설정

🎯 최종 GitHub Actions Workflow

name: Deploy to GitHub Pages

on:
  push:
    branches: ["main"]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Create env file
        run: |
          echo "VITE_APP_API_URL=${{ secrets.VITE_APP_API_URL }}" > .env.production
          echo "NODE_ENV=production" >> .env.production

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build
        env:
          VITE_APP_API_URL: ${{ secrets.VITE_APP_API_URL }}

      - name: Add CNAME file
        run: echo 'blu2print.site' > ./dist/CNAME

      - name: Setup Pages
        uses: actions/configure-pages@v4

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: './dist'

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

---

🎉 4. 최종 결과

✅ GitHub Pages 배포 성공!
✅ base 경로가 자동으로 설정되어 정적 파일이 정상적으로 로딩됨
✅ 배포 후 GitHub Actions에서 자동으로 배포된 페이지 URL을 확인 가능

---

📌 5. 결론 및 배운 점

1️⃣ GitHub Pages용 artifact 업로드는 upload-pages-artifact@v3를 사용해야 함.
2️⃣ Vite 프로젝트를 GitHub Pages에 배포할 때 configure-pages@v4를 사용하여 base를 자동 설정해야 함.