Vercel이란 무엇인가: 원클릭 배포의 개념

휴대폰 화면에 자기가 만든 웹사이트가 떠 있는 것을 처음 보는 순간의 감각은 독특합니다. 내 컴퓨터호스트에서만 존재하던 페이지가, 카페에서 커피를 마시며 열어본 모바일 브라우저에도 동일하게 나타납니다. 그 사이에서 무슨 일이 일어난 것일까요?

내 컴퓨터호스트(localhost)는 내 컴퓨터에서만 접근할 수 있는 주소입니다. 클로드 코드가 개발 서버를 시작하면 localhost:3000이나 localhost:51006 같은 주소가 부여되는데, 이 주소는 같은 컴퓨터의 브라우저에서만 열립니다. 다른 사람이 이 주소를 입력하면 아무것도 나오지 않습니다. 웹사이트의 코드가 내 컴퓨터의 메모리에서만 실행되고 있기 때문입니다.

이 코드를 세상에 내보내려면, 24시간 가동되는 서버에 코드를 올리고, 그 서버에 고유한 주소를 연결해야 합니다. 전통적으로 이 과정은 서버 임대, 운영 체제 설정, 웹 서버 소프트웨어 설치, SSL 인증서 발급, 도메인 연결 등 수십 단계를 거쳐야 했습니다.

버셀(Vercel)은 이 복잡한 과정을 하나의 버튼 클릭으로 압축한 서비스입니다. 깃허브 리포지토리를 선택하고 "Deploy" 버튼을 누르면, 버셀이 코드를 가져와서 구축하고, 전 세계에 분산된 서버에 배포하고, 자동으로 HTTPS 인증서를 설정하고, 고유한 URL을 부여합니다.

[그림 15-1] 로컬 개발에서 라이브 배포까지의 전환 과정 개념도

버셀의 무료 플랜으로도 개인 프로젝트와 포트폴리오 사이트를 운영하는 데 충분합니다. 배포된 사이트에는 프로젝트명.vercel.app 형태의 기본 도메인이 부여됩니다. 이 도메인으로도 누구나 접속할 수 있지만, 자신만의 도메인을 연결하는 것도 가능합니다.

여기서 이해해야 할 핵심은, 버셀이 하는 일은 "코드를 받아서 웹사이트로 만들어 주는 것"이라는 점입니다. 깃허브에 코드가 있고, 버셀에 배포 설정이 있으면, 그 둘을 연결하는 파이프라인이 완성됩니다.

깃허브 리포지토리와 Vercel 연결

버셀에 가입할 때 깃허브 계정으로 로그인하면, 이후의 모든 과정이 간결해집니다. 버셀이 깃허브 리포지토리 목록에 바로 접근할 수 있기 때문입니다.

연결 과정은 다음과 같습니다.

버셀 대시보드에서 "Add New Project"를 클릭합니다. 화면에 본인의 깃허브 리포지토리 목록이 나타납니다. 배포할 리포지토리를 찾아 "Import" 버튼을 클릭합니다. 구축 설정 화면이 나타나는데, Next.js나 React 같은 프레임워크를 자동으로 감지합니다. "Deploy" 버튼을 클릭하면 구축가 시작됩니다.

수십 초에서 수 분 사이에 구축가 완료되고, 고유한 URL이 생성됩니다. 이 URL을 브라우저에 입력하면 내 웹사이트가 나타납니다. 휴대폰에서 열어도, 다른 나라의 컴퓨터에서 열어도 같은 페이지가 나타납니다.

[그림 15-2] 버셀 대시보드에서 깃허브 리포지토리를 임포트하는 화면

그런데 첫 배포에서 문제가 발생할 수 있습니다. 앞 장에서 다룬 웹사이트 사례를 떠올려 보겠습니다. 블렌더 제품 랜딩 페이지를 버셀에 배포했더니, 스크롤 애니메이션에 사용되는 프레임 이미지 파일들이 빠져 있었습니다. 내 컴퓨터에서는 완벽하게 작동하던 사이트가, 배포 후에는 블렌더 이미지 없이 텍스트만 덩그러니 나타났습니다.

원인은 .gitignore 파일이었습니다. 이미지 프레임 폴더가 깃의 추적 대상에서 제외되어 있었기 때문에, 깃허브에 푸시되지 않았고, 버셀도 그 파일을 받지 못한 것입니다. 해결 방법은 간단합니다. 클로드 코드에게 "프레임 이미지도 깃허브에 포함시켜서 다시 푸시해 줘"라고 요청하면, .gitignore 설정을 수정하고, 누락된 파일을 추가 커밋하여 푸시합니다.

이 경험이 보여주는 교훈이 있습니다. 내 컴퓨터 환경과 배포 환경은 다릅니다. 내 컴퓨터에는 있지만 깃 추적 대상이 아닌 파일은 배포 환경에 존재하지 않습니다. 배포 전에 "내 리포지토리에 사이트 구동에 필요한 모든 파일이 포함되어 있는가?"를 확인하는 습관이 필요합니다.

버셀 대시보드의 "Deployments" 탭에서는 모든 배포 이력을 확인할 수 있습니다. 문제가 있는 배포를 이전 버전으로 롤백(rollback)하는 것도 클릭 한 번으로 가능합니다.

[그림 15-3] 버셀 배포 이력 화면: 각 배포의 상태와 롤백 옵션

실시간 반영 파이프라인: 코드 변경이 자동으로 반영되는 구조

버셀과 깃허브의 연결이 완성되면, 이후부터는 놀라울 정도로 매끄러운 워크플로우가 작동합니다.

과정은 이렇습니다. 클로드 코드에서 웹사이트 코드를 수정합니다. 내 컴퓨터호스트에서 변경 사항을 확인합니다. 마음에 들면 "깃허브에 푸시해 줘"라고 요청합니다. 깃허브에 새로운 커밋이 도착합니다. 버셀이 이 변경을 자동으로 감지합니다. 새로운 구축가 시작되고, 완료되면 라이브 사이트가 자동으로 업데이트됩니다.

[그림 15-4] 라이브 업데이트 파이프라인: 클로드 코드 → 깃허브 → 버셀 → 라이브 사이트

이 파이프라인에서 핵심적인 안전장치는 "명시적 푸시"입니다. 내 컴퓨터에서 아무리 많이 수정해도, "깃허브에 푸시해 줘"라고 말하기 전까지는 라이브 사이트에 아무런 영향이 없습니다. 이것은 의도적인 설계입니다.

CLAUDE.md 파일에 이 원칙을 명시해 두면 안전합니다. "우리는 변경 사항을 깃허브에 동기화하고, 깃허브가 자동으로 버셀에 푸시할 것이다. 그러나 내 컴퓨터에서 변경할 때는 항상 내 컴퓨터호스트에서 먼저 검증하고, 내가 명시적으로 깃허브에 커밋하거나 푸시하라고 말하기 전까지는 절대로 원격에 반영하지 마라." 이런 지침이 있으면 클로드 코드가 실수로 작업 중인 코드를 푸시하는 상황을 방지할 수 있습니다.

실시간 반영의 속도도 인상적입니다. 앞선 사례에서 히어로 버튼에 글로우 효과를 추가한 뒤 깃허브에 푸시하자, 수 분 안에 버셀의 배포가 완료되었고, 라이브 사이트를 새로고침하면 글로우 버튼이 나타났습니다.

깃허브의 커밋 이력에는 "add glowing pulse effect to hero join the community button"이라는 메시지가 남았고, 버셀의 배포 이력에도 대응하는 배포 기록이 생겼습니다.

이 구조를 통해 사실상 세 개의 환경이 자연스럽게 만들어집니다.

개발 환경(내 컴퓨터호스트): 자유롭게 수정하고 검증하는 공간입니다. 실패해도 아무 영향이 없습니다.

스테이징 환경(깃허브): 코드의 변경 이력이 기록되는 공간입니다. 여기에 올라간 코드는 정리된 상태여야 합니다.

프로덕션 환경(버셀 라이브 사이트): 실제 사용자가 접속하는 공간입니다. 깃허브에서 자동으로 배포됩니다.

[그림 15-5] 세 가지 환경의 관계: 개발 → 스테이징 → 프로덕션

도메인 연결과 환경 변수 설정

버셀이 자동으로 부여하는 프로젝트명.vercel.app 도메인은 기능적으로 완전하지만, 전문적인 인상을 주기에는 부족합니다. 자신만의 도메인을 연결하면 사이트의 신뢰도가 올라갑니다.

도메인 연결 절차는 버셀의 프로젝트 설정에서 시작합니다. "Settings" 탭의 "Domains" 섹션으로 이동합니다. 여기서 두 가지 선택지가 있습니다. 버셀에서 직접 도메인을 구매하거나, 이미 보유한 도메인을 추가하는 것입니다.

기존 도메인을 연결하려면 DNS 설정(Domain Name System configuration)을 변경해야 합니다. 도메인을 구매한 서비스(예: 가비아, 네임칩, 구글 도메인 등)의 관리 패널에서 DNS 레코드를 버셀이 안내하는 값으로 변경합니다. 버셀의 안내 화면이 어떤 레코드를 어떤 값으로 설정해야 하는지 구체적으로 알려주므로, 기술적 배경 지식이 없어도 따라할 수 있습니다.

[그림 15-6] 버셀 도메인 설정 화면과 DNS 레코드 구성 예시

DNS 변경이 전파되는 데에는 수 분에서 최대 48시간이 걸릴 수 있습니다. 대부분의 경우 30분 이내에 적용되지만, 도메인을 연결한 직후에 접속이 안 되더라도 당황할 필요는 없습니다.

환경 변수(environment variable) 설정은 프로젝트가 외부 서비스와 연동될 때 필요합니다. API 키, 데이터베이스 연결 문자열, 인증 모델이 세는 글 조각(token) 같은 민감한 정보는 코드에 직접 적지 않고, 환경 변수로 분리해서 관리합니다.

버셀의 프로젝트 설정에서 "Environment Variables" 섹션을 찾으면, 키-값(key-value) 쌍을 등록할 수 있습니다. 예를 들어 NEXT_PUBLIC_API_KEY라는 키에 실제 API 키 값을 입력합니다. 이 값은 버셀의 서버에만 저장되며, 깃허브 리포지토리에는 포함되지 않습니다. 코드에서는 process.env.NEXT_PUBLIC_API_KEY로 이 값을 참조합니다.

환경 변수를 사용하는 이유는 보안입니다. 깃허브 리포지토리가 공개되어 있어도 API 키가 노출되지 않습니다. 그리고 개발 환경과 배포 환경에서 서로 다른 값을 사용할 수 있습니다. 내 컴퓨터에서는 검증용 API 키를, 프로덕션에서는 실제 API 키를 사용하는 식입니다.

[그림 15-7] 버셀 환경 변수 설정 화면

환경 변수를 변경하면 버셀이 자동으로 재배포를 실행합니다. 코드를 수정하지 않았는데도 사이트가 재배포되는 경우, 환경 변수 변경이 원인일 수 있습니다.

사이트가 라이브로 올라갔고, 도메인도 연결되었고, 환경 변수도 설정되었습니다. 브라우저에 주소를 입력하면 누구에게나 같은 페이지가 나타납니다. 그러나 배포가 끝이 아닙니다. 라이브 사이트는 시간이 지나면서 새로운 종류의 문제를 만나게 됩니다. 개발 환경에서는 보이지 않던 문제들입니다.