열심히 만든 블로그를 배포한 후, 설정해 둔 커스텀 도메인으로 접속이 되지 않아 당황하셨을 것 같습니다. 이 문제는 많은 분들이 겪는 흔한 상황이며, 원인만 알면 간단하게 해결할 수 있습니다.
Hugo Blowfish 테마를 포함한 대부분의 Hugo 사이트 배포 시 CNAME 파일이 사라지는 문제의 해결 방법을 명확하게 알려드리겠습니다.
문제의 원인: Hugo 빌드 프로세스#
이 문제의 원인을 먼저 이해하면 해결책을 찾기 쉽습니다.
hugo 명령어를 실행하여 사이트를 빌드하면, Hugo는 기존의 public 폴더를 완전히 삭제하고 콘텐츠, 테마, 설정 등을 바탕으로 새로운 public 폴더를 생성합니다.
따라서 배포 전에 수동으로 public 폴더 안에 CNAME 파일을 넣어두었다면, 다음 빌드 시점에서 해당 파일이 예외 없이 삭제되는 것입니다.
해결 방법: static 폴더 활용하기#
가장 확실하고 올바른 해결 방법은 Hugo의 static 폴더를 활용하는 것입니다. static 폴더 안의 모든 파일과 폴더는 빌드 시점에 public 폴더 안으로 그대로 복사됩니다.
이 원리를 이용하여 CNAME 파일이 항상 최종 결과물에 포함되도록 할 수 있습니다.
CNAME 파일 생성하기#
메모장이나 코드 에디터를 열어 아무 내용 없이 여러분의 커스텀 도메인 주소만 정확하게 입력합니다.
파일 내용 예시:
blog.example.com
http:// 나 https:// 와 같은 프로토콜은 포함하지 마십시오. 오직 도메인 주소만 적어야 합니다.static 폴더에 CNAME 파일 배치하기#
생성한 CNAME 파일을 Hugo 프로젝트의 루트(최상위)에 있는 static 폴더 안으로 옮깁니다. static 폴더가 없다면 직접 생성하시면 됩니다.
올바른 파일 경로:
내-휴고-프로젝트/
├── archetypes/
├── content/
├── data/
├── layouts/
├── static/
│ └── CNAME <-- 바로 여기에 위치해야 합니다.
└── hugo.toml
빌드 및 확인#
이제 로컬 환경에서 hugo 명령어를 실행하여 사이트를 빌드해 보십시오. 빌드가 완료된 후 public 폴더 안을 확인하면 CNAME 파일이 생성된 것을 볼 수 있습니다.
이제 이 상태로 원격 저장소에 푸시(Push)하거나 서버에 배포하면, CNAME 파일이 항상 포함되어 커스텀 도메인이 정상적으로 연결됩니다.
GitHub Actions 배포 환경에서의 추가 확인 사항#
만약 GitHub Actions를 사용하여 GitHub Pages에 자동 배포하고 있다면, 워크플로우(.github/workflows/deploy.yml 등) 파일을 확인해 볼 필요가 있습니다.
몇몇 Hugo 배포 워크플로우 템플릿에는 빌드 후에 CNAME 파일을 생성하는 명령어가 포함되어 있기도 합니다.
# .github/workflows/deploy.yml 파일 예시
- name: Build with Hugo
run: hugo --minify
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./public
cname: blog.example.com # <--- 이 부분이 CNAME을 생성합니다.
만약 위와 같이 cname: 설정이 워크플로우 파일에 있다면, 이 값을 본인의 도메인으로 수정하는 것만으로도 문제가 해결될 수 있습니다. 하지만 static 폴더에 CNAME 파일을 두는 방법이 Hugo의 표준적인 방식이며, 배포 환경이 바뀌더라도 동일하게 적용할 수 있어 더욱 권장되는 방법입니다.
마무리#
핵심은 “Hugo가 public 폴더를 새로 만들기 전에, CNAME 파일을 static 폴더에 미리 준비해 둔다” 는 것입니다. 이 간단한 규칙만 기억하시면 앞으로 Hugo 사이트를 운영하면서 커스텀 도메인 문제로 고민할 일이 없으실 겁니다.