웹사이트 배포
개요
이 스킬은 이미 생성된 웹사이트를 GitHub Pages에 배포하는 과정을 안내합니다. 예상되는 프로젝트는 GitHub 저장소에 저장된 Astro 정적 사이트이며, 소스 파일은 커밋되어 있고 배포는 GitHub Actions로 처리됩니다.
이 스킬은 웹사이트 자체가 이미 존재한다고 가정합니다. 사용자가 요청하지 않는 한 웹사이트를 재설계하지 마십시오.
배포 모델
현재 개인 웹사이트 워크플로우에는 다음 설정을 사용하세요.
- Git으로 소스 코드를 추적합니다.
node_modules/,dist/,.astro/,tmp/등 생성되거나 의존성 폴더는 무시합니다.npm.cmd run build로 사이트를 빌드합니다.- GitHub Actions에서 GitHub Pages로 배포합니다.
- 로컬 개발은
http://localhost:4321/에서 유지합니다. - 프로젝트 Pages URL(예:
https://USERNAME.github.io/REPOSITORY/)의 경우 GitHub Actions 빌드 중에만 Astrobase경로를 사용합니다.
배포 전
간단한 명령으로 준비 상태를 확인하세요.
git status
npm.cmd run build
다음 파일 또는 설정이 있는지 확인하세요.
package.jsonastro.config.mjs.gitignore.github/workflows/deploy.ymlsrc/public/
이 프로젝트의 경우 astro.config.mjs는 로컬 및 GitHub Pages 빌드를 모두 지원해야 합니다. 예:
import { defineConfig } from "astro/config";
const isGithubPagesBuild = process.env.GITHUB_ACTIONS === "true";
export default defineConfig({
site: "https://USERNAME.github.io",
base: isGithubPagesBuild ? "/REPOSITORY" : "/",
});
로컬 공개 자산이나 내부 페이지에 링크할 때 Astro 페이지/레이아웃에서 URL 헬퍼를 사용하세요.
const base = import.meta.env.BASE_URL;
const url = (path: string) => {
const normalizedBase = base.endsWith("/") ? base : `${base}/`;
const normalizedPath = path.replace(/^\/+/g, "");
return `${normalizedBase}${normalizedPath}`;
};
GitHub Actions 워크플로우
다음과 같은 Pages 워크플로우를 사용하세요.
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@v7
- name: Build with Astro
uses: withastro/action@v6
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@v5
필요한 경우 액션을 간단히 설명하세요.
actions/checkout@v7: GitHub Actions 러너에 저장소를 다운로드합니다.withastro/action@v6: 의존성을 설치하고, Astro 사이트를 빌드하며, Pages 아티팩트를 준비합니다.actions/deploy-pages@v5: 빌드된 아티팩트를 GitHub Pages에 게시합니다.
@vN 접미사는 액션의 주요 버전을 고정합니다.
저장소 및 커밋 단계
사용자가 배포 준비가 된 소스 변경 사항을 커밋하고 푸시하도록 안내하세요.
git status
git add .
git commit -m "Prepare website deployment"
git push origin main
Git에서 LF will be replaced by CRLF와 같은 줄 끝 경고가 표시되면, 이는 Windows 줄 끝 정규화 경고이며 일반적으로 배포를 차단하지 않는다고 설명하세요.
Git에서 구성된 사용자 ID가 없다고 보고하면, 커밋하기 전에 저장소 또는 전역 ID를 구성하세요. 개인정보 보호가 중요한 경우 사용자의 GitHub noreply 이메일을 사용하세요.
GitHub Pages 설정
GitHub에서 사용자를 안내하세요.
- GitHub에서 저장소를 엽니다.
Settings로 이동합니다.Pages로 이동합니다.Build and deployment아래에서Source를GitHub Actions로 설정합니다.- GitHub에 저장 버튼이 표시되면 저장합니다.
Actions탭으로 이동하여 최신 배포 실행을 엽니다.- 워크플로우가 성공할 때까지 기다립니다.
- GitHub에서 표시하는 Pages URL을 엽니다.
프로젝트 사이트의 경우 예상 URL은 일반적으로 다음과 같습니다.
https://USERNAME.github.io/REPOSITORY/
확인
배포 후 다음을 확인하세요.
- 홈페이지가 로드됩니다.
- 탐색 링크가 작동합니다.
- 이미지가 로드됩니다.
- CV PDF와 같은 다운로드 가능한 파일이 올바르게 열립니다.
- 브라우저 URL에 프로젝트 Pages의 저장소 경로가 포함됩니다.
- 생성된 HTML에
/REPOSITORYprojects,/REPOSITORYprofile.jpg, 또는/REPOSITORYfile.pdf와 같은 잘못된 경로가 나타나지 않습니다.
배포된 사이트가 손상되었지만 로컬 미리보기는 정상인 경우, 먼저 base-path 처리를 검사하세요.
GitHub Actions가 실패하면 실패한 단계를 검사하세요.
- 체크아웃 실패: 저장소 또는 권한 문제.
- 설치/빌드 실패: 의존성, Astro 또는 소스 코드 문제.
- 배포 실패: GitHub Pages 소스/권한/설정 문제.
완료 기준
다음 조건을 만족하면 배포 작업이 완료된 것으로 간주합니다.
- 로컬 빌드가 통과되었습니다.
- 소스 변경 사항이 커밋되고 푸시되었습니다.
- GitHub Pages 소스가 GitHub Actions로 설정되었습니다.
- Actions 배포 실행이 성공했습니다.
- 공개 Pages URL이 웹사이트를 올바르게 로드합니다.