Vercel 커스텀 도메인 연결하기 — CLI, 가비아 A레코드, HTTPS 검증까지
여름 멘토링용으로 만든 작은 교육용 웹앱을 Vercel에 올렸습니다. 빌드 도구도 없는 순수 정적 사이트라 배포는 git push 한 번으로 끝났는데, 막상 주소가 프로젝트명-xxxx.vercel.app 같은 임의의 문자열이라 영 정이 가지 않았습니다. 마침 개인 기술 블로그 도메인을 갖고 있어서, 그 커스텀 도메인의 서브도메인 하나를 이 앱에 붙여 주기로 했습니다.
작업 자체는 길지 않았습니다. 다만 돌이켜보면 "한 줄이면 끝"이라고 넘기기엔 짚어 둘 만한 지점이 몇 개 있었고, 정리해 두는 편이 다음 번의 저에게 도움이 되겠다는 생각이 들었습니다.
왜 기본 도메인이 아니라 커스텀 도메인이었나
vercel.app 기본 주소도 동작에는 아무 문제가 없습니다. 그럼에도 굳이 도메인을 붙인 이유는 단순합니다. 기억하기 쉬운 주소를 주고 싶었고, 이왕이면 블로그와 같은 도메인 아래로 묶여 있는 편이 일관성 있다고 느꼈기 때문입니다.
트레이드오프랄 것도 거의 없었습니다. 커스텀 도메인을 붙여도 기존 vercel.app 주소는 그대로 살아 있어 잃는 것이 없고, 들이는 비용은 DNS 레코드 한 줄과 인증서 발급을 기다리는 몇 분 정도입니다.
Vercel CLI로 현황부터 확인하기
Vercel은 대시보드뿐 아니라 vercel CLI를 제공합니다(이 글은 CLI 54.x 기준입니다). 대시보드를 오가지 않고 터미널에서 상태를 확인하고 명령을 내릴 수 있어, 저는 CLI 쪽이 편했습니다.
한 가지 새삼 깨달은 점은, 로그인이 "이 터미널 세션" 단위가 아니라 머신 단위라는 것이었습니다. 한 번 vercel login을 해 두면 토큰이 로컬에 저장되어, 이후 어느 터미널을 열든 인증된 상태로 명령을 쓸 수 있었습니다.
vercel whoami # 로그인된 계정 확인
vercel projects ls # 프로젝트 목록Project Name Latest Production URL Updated
deepsea https://deepsea-eosin.vercel.app ...도메인 추가는 한 줄, 문제는 apex냐 서브도메인이냐
도메인을 프로젝트에 붙이는 명령 자체는 정말 한 줄입니다.
vercel domains add deepsea.kichang.info deepsea여기서 잠깐 멈춰서 따져봐야 하는 것이 있습니다. 루트(apex) 도메인이냐 서브도메인이냐에 따라 등록할 DNS 레코드가 달라지기 때문입니다.
| 구분 | 예시 | 레코드 타입 | 값 |
|---|---|---|---|
| 루트(apex) | example.com | A | 76.76.21.21 |
| 서브도메인 | sub.example.com | A 또는 CNAME | 76.76.21.21 또는 cname.vercel-dns.com |
제 경우는 블로그 도메인의 서브도메인이었고, Vercel이 권장하는 대로 A레코드(76.76.21.21)를 쓰기로 했습니다.
여기서 함정이 하나 있습니다. 도메인을 추가하면 Vercel은 두 가지 방법을 제시합니다. (a) DNS에 레코드 한 줄을 추가하거나, (b) 네임서버 자체를 Vercel로 바꾸는 것입니다. 저처럼 같은 도메인의 루트에 이미 다른 사이트(이 블로그)가 올라가 있는 경우, (b)를 따라가면 안 됩니다. 네임서버를 통째로 옮기면 그 도메인의 모든 DNS를 Vercel이 관리하게 되어, 정작 블로그가 떠 있던 기존 호스팅으로의 연결이 끊기기 때문입니다. 서브도메인 하나만 추가하는 것이 목적이라면 (a) 레코드 한 줄로 충분합니다.
가비아에서 A레코드 등록하기
제 도메인은 가비아에서 관리하고 있습니다. 영어권 자료는 대부분 Cloudflare나 Namecheap 기준이라, 가비아 화면을 기준으로 정리해 둡니다. (어느 업체를 쓰는지는 dig NS나 WHOIS로 어차피 공개되는 정보입니다.)
가비아 → My가비아 → 도메인 → DNS 관리 → 레코드 추가
타입 : A
호스트 : deepsea (서브도메인 앞부분만)
값/IP : 76.76.21.21
TTL : 3600
→ 행 오른쪽 "확인" 클릭 → 하단 "저장" 클릭가비아는 행을 추가한 뒤 "확인"으로 행을 확정하고, 다시 "저장"을 눌러야 실제로 반영됩니다. 두 단계로 나뉘어 있어 처음에는 저장을 빼먹기 쉽습니다.
됐다고 믿지 말고, 계층별로 확인하기
사실 이 글에서 가장 적어 두고 싶었던 부분입니다. "추가했으니 되겠지"가 아니라, DNS가 동작하는 각 계층을 차례로 확인하면 문제가 생겨도 어디서 막혔는지 바로 알 수 있습니다.
먼저 레코드가 가비아에 들어갔는지, 그리고 바깥으로 전파됐는지를 나눠서 봅니다.
# 권한 네임서버(가비아)에 직접 질의 — 레코드가 등록됐는가
dig +short deepsea.kichang.info @ns1.gabia.co.kr
# 공개 DNS(구글)로 질의 — 바깥까지 전파됐는가
dig +short deepsea.kichang.info @8.8.8.8권한 네임서버에서 먼저 76.76.21.21이 나오고, 잠시 뒤 8.8.8.8에서도 같은 값이 나오면 전파가 끝난 것입니다.
그다음 실제로 사이트가 응답하는지 봅니다. 여기서 흥미로운 지점이 있었는데, HTTP는 곧바로 200을 주는데 HTTPS는 잠시 실패했습니다.
curl -sI https://deepsea.kichang.info # 처음엔 SSL 에러HTTPS 인증서(Let's Encrypt)가 아직 발급 전이라 그렇습니다. DNS가 정상으로 확인되면 Vercel이 자동으로 인증서를 발급하는데, 제 경우 2분 남짓 걸렸습니다. 발급이 끝나면 정상적으로 응답이 옵니다.
HTTP/2 200
server: Vercel마지막으로 인증서가 누구에게서, 언제까지 발급됐는지까지 확인했습니다.
echo | openssl s_client -connect deepsea.kichang.info:443 \
-servername deepsea.kichang.info 2>/dev/null \
| openssl x509 -noout -issuer -datesissuer=C=US, O=Let's Encrypt, CN=...
notBefore=...
notAfter=...발급자가 Let's Encrypt로 찍히고 유효기간이 잡혀 있으면, 이후 갱신은 Vercel이 알아서 처리합니다.
마무리
돌이켜보면 커스텀 도메인 연결에서 헷갈리는 대부분은 "안 되는 것"이 아니라, 아직 전파 중이거나 발급 중인 것을 안 되는 것으로 오해하는 데서 옵니다. 전파(DNS)와 발급(HTTPS)을 분리해서, 각 계층을 dig → curl → openssl 순으로 확인하는 습관을 들이니 마음이 한결 편했습니다.
작은 정적 사이트 하나에 주소를 붙였을 뿐이지만, 각 계층이 무슨 일을 하는지 한 번 더 들여다본 시간이었다는 생각이 듭니다.
관련 글
Traefik으로 www 리디렉션 설정하기: 404 에러 해결 과정
Traefik에서 www 서브도메인이 404 에러를 반환할 때, non-www로 리디렉션하는 설정 방법을 상세히 설명합니다. Traefik 라우터와 미들웨어를 활용해 이 문제를 해결하세요.
whois와 dig로 5분 만에 스미싱 문자 가짜 판별하기
WhatsApp 사칭 스미싱 문자를 받았습니다. 링크는 한 번도 열지 않고 whois와 dig 두 명령만으로 신규 등록 도메인·은닉된 등록자·정식과 다른 인프라를 확인해 5분 만에 가짜로 판별한 과정을, 그대로 따라 칠 수 있게 정리했습니다.
Next.js 배포 시 빈 캐시 문제 해결: 런타임 워밍에서 빌드 타임 정적 생성으로
Next.js + Coolify 환경에서 배포 직후 빈 캐시와 no available server 에러가 발생하는 문제를 해결한 경험. 런타임 캐시 워밍의 한계를 겪고, 빌드 타임 정적 생성으로 전환하여 근본적으로 해결했습니다.