[GitHub Pages] 커스텀 도메인 연결 및 www 설정 완벽 가이드

Vite로 만든 포트폴리오를 가비아에서 구매한 한글 도메인에 연결하고, GitHub Actions로 자동 배포 환경을 구축하는 과정에서 겪은 시행착오와 해결 방법을 공유합니다.

1. 가비아(Gabia) DNS 설정 (A 레코드 & CNAME)

가비아 DNS 관리 툴에서 아래와 같이 총 5개의 레코드를 등록해야 합니다.

• A 레코드 (@): 루트 도메인(박성진.com)을 GitHub 서버로 연결합니다. GitHub에서 제공하는 4개의 IP를 모두 등록하는 것이 안정적입니다.
  • 185.199.108.153
  • 185.199.109.153
  • 185.199.110.153
  • 185.199.111.153
• CNAME (www): www가 붙은 주소로 접속해도 잘 연결되도록 설정합니다.
  • 호스트: www
  • 값/위치: 내아이디.github.io. (마지막에 마침표 필수)

 

 

Tip: 한글 도메인은 내부적으로 xn--... 형태의 퓨니코드(Punycode)로 변환됩니다. 깃허브 설정창에 이 이름이 떠도 당황하지 마세요!

---

2. GitHub Pages 커스텀 도메인 등록

GitHub 저장소의 Settings > Pages 메뉴로 이동합니다.

1. Custom domain 칸에 박성진.com을 입력하고 Save를 누릅니다.
2. DNS check successful이라는 초록색 메시지가 뜨면 성공입니다.
3. Enforce HTTPS를 반드시 체크하여 보안 연결을 적용합니다.

---

3. 트러블슈팅: 접속 시 "흰 화면"만 나올 때

도메인 연결 후 사이트가 하얗게 나온다면 브라우저 콘솔(F12)을 확인해 보세요. 404 Not Found 에러가 뜬다면 파일 경로 설정 문제입니다.

• 원인: 기존의 아이디.github.io/저장소명/ 구조에서 루트 주소인 / 구조로 바뀌었기 때문입니다.
• 해결: vite.config.ts 파일에서 base 설정을 수정합니다.
   
  TypeScript

  export default defineConfig({
    base: '/', // 기존 '/저장소명/'에서 '/'로 변경
  });
  

---

4. GitHub Actions로 자동 배포 구축 (중첩 폴더 구조)

매번 npm run deploy를 치는 수고를 덜기 위해 GitHub Actions를 설정합니다. 특히 프로젝트가 하위 폴더에 있는 중첩 구조라면 working-directory 설정이 핵심입니다.

1. 최상위 루트에 .github/workflows/deploy.yml 파일을 생성합니다.
2. 중요 포인트:
   • working-directory: 실제 프로젝트 폴더명을 지정합니다.
   • path: 빌드된 파일이 있는 dist 폴더의 경로를 정확히 적어줍니다.
   • environment: 배포 환경을 github-pages로 선언하여 권한 오류를 방지합니다.

---

5. 도메인 설정 유지하기 (CNAME 파일)

배포 시 커스텀 도메인 설정이 자꾸 초기화된다면 프로젝트의 public 폴더 안에 **CNAME**이라는 파일을 만드세요.

• 파일명: CNAME (확장자 없음)
• 내용: 박성진.com

이렇게 하면 빌드 결과물에 항상 도메인 정보가 포함되어 설정이 유지됩니다.