Hugo와 Vercel로 나만의 기술 블로그 구축하기: 완벽 구축 가이드 & 트러블슈팅

드디어 개인 기술 블로그 Rico's Tech Blog (ricosheaven.com)를 세상에 공개했습니다! 가볍고 빠른 정적 사이트 생성기(SSG)인 Hugo와 자동 배포 플랫폼인 Vercel의 조합으로 시작했는데, 초기 환경 세팅부터 배포 완료까지 수많은 기술적 디버깅 과정을 거치게 되었습니다.

오늘 하루 동안 Hugo 블로그를 처음부터 구축하고 Vercel에 배포하기까지 진행했던 모든 과정과, 중간에 마주쳤던 난관들의 해결법을 하나의 가이드 문서로 정리합니다.

1. 로컬 개발 환경 구축 & Hugo 사이트 생성

가장 먼저 로컬 Mac 환경에서 Hugo 사이트를 생성하고 블로그 테마로 가장 널리 쓰이는 PaperMod를 적용했습니다. Vercel 배포 시 Git 서브모듈(Submodule) 경로 문제로 빌드가 깨지는 현상을 방지하기 위해, 테마를 '일반 폴더' 형태로 포함시키는 방식으로 구축했습니다.

# 1. 새 블로그 프로젝트 폴더 생성 및 이동
mkdir my-blog && cd my-blog

# 2. Hugo 사이트 생성
hugo new site . --force

# 3. PaperMod 테마 클론 및 서브모듈 속성 제거 (일반 폴더화)
git clone https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
rm -rf themes/PaperMod/.git

# 4. Git 추적 방지 (.gitignore 설정)
echo "/public/" >> .gitignore
echo "/resources/" >> .gitignore
echo ".hugo_build.lock" >> .gitignore

2. 블로그 설정 파일 (hugo.yaml) 작성

블로그의 타이틀, 언어, 테마 설정을 정의하기 위해 프로젝트 루트에 hugo.yaml 설정 파일을 작성했습니다.

⚠️ 주의사항: theme: 'PaperMod' 설정의 대소문자는 themes/PaperMod 폴더의 명칭과 토씨 하나 틀리지 않고 정확히 일치해야 Hugo 엔진이 테마를 읽을 수 있습니다.

baseURL: 'https://ricosheaven.com/'
languageCode: 'ko-kr'
title: "Rico's Tech Blog"
theme: 'PaperMod'

params:
  env: production
  title: "Rico's Tech Blog"
  description: 'IT 개발 및 지식 기록 공간'

  homeInfoParams:
    Title: "안녕하세요!"
    Content: "IT 개발 및 기술 지식을 기록하는 공간입니다."

3. 첫 포스팅 작성 및 GitHub 원격 저장소 업로드

테스트용 포스트 마크다운 파일(content/posts/first-post.md)을 작성한 뒤, GitHub에 새 레포지토리를 만들고 소스 코드를 Push했습니다.

# 테스트 글 생성
hugo new posts/first-post.md

# Git 초기화 및 커밋
git init
git branch -M main
git add .
git commit -m "Initial commit - Fresh Hugo setup"

# GitHub 저장소 연결 및 푸시
git remote add origin https://github.com/Rico83-KR/my-blog.git
git push -u origin main --force

4. Vercel 배포 및 커스텀 도메인 연결

Vercel 대시보드에서 GitHub 레포지토리를 연동하여 자동 배포 파이프라인을 구축했습니다.

Vercel Dashboard ➔ Add New... ➔ Project 클릭
GitHub의 my-blog 레포지토리 Import
Framework Preset으로 Hugo 선택 후 Deploy 진행
배포 성공 후 Settings ➔ Domains에 커스텀 도메인(ricosheaven.com) 연결

5. 시행착오 및 트러블슈팅 (Troubleshooting)

블로그 구축 과정에서 겪었던 가장 치명적인 문제들과 그 원인, 해결책을 정리했습니다.

Issue 1 설정 파일 키값 오타 및 public 폴더 Git 추적 문제

증상: hugo.yaml 파일 수정 후 커밋해도 메인 타이틀 변경이 원격에 반영되지 않음.

원인: title: 대신 tiltle:로 오타가 들어갔으며, 로컬 빌드 결과물인 /public/ 폴더가 Git에 올려져 Vercel이 이전 정적 파일만 내뱉는 현상 발생.

해결: 오타 수정 후 Git 추적 목록에서 public 폴더를 강제 제거했습니다.

git rm -r --cached public
git commit -m "Remove public build files from tracking"
git push origin main

Issue 2 Vercel 배포 후 Recent content on Hugo 민낯 화면만 출력되는 현상

증상: Vercel 배포 상태는 Ready이지만, PaperMod 디자인이 적용되지 않고 흰 바탕에 Recent content on Hugo -- gohugo.io 텍스트만 보이는 현상.

원인: Vercel의 기본 Hugo 빌더 엔진 버전이 구버전으로 고정되어 있어서 최신 PaperMod 테마 템플릿 파싱에 실패함.

💡 최종 해결책 (HUGO_VERSION 지정):
Vercel 프로젝트 대시보드 ➔ Settings ➔ Environment Variables로 이동하여 로컬과 동일한 최신 Hugo 버전을 환경 변수로 지정해 주었습니다.

Key: HUGO_VERSION
Value: 0.164.0

환경 변수 추가 후 Deployments 탭에서 Redeploy (Use existing Build Cache 체크 해제)를 실행하자 테마가 정상적으로 적용되었습니다!

6. 마치며

가벼운 마음으로 시작한 정적 블로그 구축이었지만, 로컬 개발 환경과 Cloud CI/CD 빌드 서버 간의 엔진 버전 일치, Git 추적 관리 등의 중요성을 깊이 깨닫는 계기가 되었습니다.

모든 환경이 완벽하게 들어맞아 배포된 만큼, 앞으로 이 공간에 알고리즘, 트러블슈팅, 신기술 공부 기록들을 차곡차곡 채워 나가겠습니다!