개발자 매튜 | 우리는 Vercel로 간다! 프론트엔드 배포 가이드

내가 열심히 만든 웹페이지를 세상에 공유못하면 억울하잖아?

대부분의 개발자들은 Visual Studio나 WebStorm 같은 IDE를 사용해 웹 애플리케이션을 만들고, localhost에서 기능이 잘 돌아가는지 확인합니다.

하지만 이렇게 로컬 환경에만 띄워진 사이트는 오직 본인 컴퓨터에서만 볼 수 있어서, 다른 사람들에게 보여줄 수 없다는 문제가 있습니다.

친구나 동료, 그리고 일반 사용자에게 내 사이트를 공유하려면, 인터넷에 배포해 누구나 접속할 수 있도록 만들어야 합니다.

이전에 제가 UMC라는 동아리에서 Chapter 11. Vercel을 활용해서 내가 만든 웹 사이트 배포하기! 라는 영상 강의로 배포하는 법을 간단하게 설명드렸습니다!

유튜브 구독좀 해주세요..🙏

이번 포스팅은 최근 외부 행사에서 참고 자료로 활용하기 위해 준비했고,

동시에 제 워크북을 보며 학습하시는 분들께도 도움이 되고자 작성했습니다!

또한, 프론트 개발자가 아니더라도 백엔드 개발자가 어드민 페이지를 만드는 경우가 간혹 존재하는데요!

처음에 배포할 때 어려움을 겪을 것 같아 커스텀 도메인을 손쉽게 연결하여

만드신 사이트를 배포할 수 있도록 기존 영상 내용을 보완해 해당 포스팅을 작성했습니다!

그렇다면 프론트엔드 배포가 필요한 이유는 무엇일까요?

우리가 개발한 웹 사이트를 세상에 공개하고 싶다면, 단순히 내 컴퓨터에서 띄워보는 것만으로는 한계가 있습니다. 다른 사람이 내 웹 사이트를 보려면 어딘가 인터넷에 접속 가능한 서버에 웹 사이트 파일들을 올려서 누구든지 주소만 알면 접속할 수 있도록 만들어야 합니다.

이 과정을 우리는 배포(Deployment) 라고 부릅니다.

프론트엔드 배포가 필요한 이유를 정리해보면 다음과 같습니다.

다른 사람들과 공유하기 위해
- 개발자뿐만 아니라 사용자, 디자이너, 클라이언트, 친구들에게 내가 만든 사이트를 보여주려면 배포가 필수입니다.
실제 서비스 환경에서 테스트하기 위해
- 로컬에서는 잘 동작하던 기능이 실제 인터넷 환경에서는 예상과 다르게 동작할 수 있습니다. 네트워크 속도, 브라우저 호환성, 모바일/PC 환경 등의 실제 상황에서의 동작을 확인하려면 배포가 필요합니다.
- 특히 Safari와 같이 특정 브라우저에서는 생각보다 많은 문제점을 유발시킵니다!! 실제 배포하거나, 특정 기기 별로 확인을 한 후에 배포를 해야하는 경우가 상당히 많습니다!!
프로젝트를 실전에 가깝게 운영해보기 위해
- 배포 경험은 단순히 코딩 실력뿐 아니라, 실무에서의 서비스 운영, 배포 자동화, 버전 관리, 에러 모니터링 등을 익힐 수 있는 좋은 경험이 됩니다.
포트폴리오/이력서용으로 활용하기 위해
- 나만의 포트폴리오 사이트나 프로젝트 데모를 배포해두면, 이력서에 URL을 첨부해 실력을 보여줄 수 있습니다.

우리는 Vercel로 간다.

아마존에서 제공하는 S3 + CloudFront 같은 다양한 배포 방법도 있지만, 저희는 **더 쉽고 빠르게 배포할 수 있는 Vercel**을 사용해보겠습니다.

Vercel은 어느 정도까지는 무료로 충분히 사용 가능하고,
손쉽게 배포할 수 있을 뿐만 아니라,
여러분이 구매한 도메인(URL)을 연결하는 것도 아주 간편합니다.

또한, 코드를 수정하고 다시 배포하는 과정도 버튼 몇 번이면 끝이라
복잡하게 배포 환경을 구성할 필요 없이 개발에만 집중할 수 있는 점이 큰 장점입니다.

Vercel을 활용한 프로젝트 배포 가이드

프로젝트를 Vercel에 배포하면, 별도의 서버 관리 없이도 간단하게 정적 사이트나 프론트엔드 애플리케이션을 호스팅할 수 있습니다.

여기서는 로컬에서 작성한 코드를 GitHub에 올리고, Vercel CLI를 이용해 배포하는 과정을 단계별로 정리합니다.

🚨 주의 사항

프로젝트 루트(프로젝트 폴더 최상위 경로)에서 모든 명령어가 실행된다고 가정합니다.
.env 파일 등 민감 정보가 담긴 환경 변수 파일은 절대 GitHub에 업로드하지 않습니다.

1. 준비 단계: GitHub에 레포지토리 생성하기

프로젝트를 Git 초기화

cd /path/to/your/project
git init
git add .
git commit -m "Initial commit"bash

GitHub에서 새 레포지토리 생성
- GitHub 웹사이트에서 ‘New Repository’ 버튼을 클릭합니다.
- 레포지토리 이름(예: my-app)을 입력하고, 적절히 공개/비공개 여부를 선택합니다.
- 로컬 레포지토리와 연결할 원격 레포 URL을 복사합니다.

로컬 레포지토리에 원격 추가 후 푸시

git remote add origin https://github.com/your-username/my-app.git
git branch -M main        # 기본 브랜치를 main으로 사용할 경우
git push -u origin mainbash

.env 같은 환경 변수 파일은 절대 담지 않도록 .gitignore에 추가하세요.
```
# .gitignore 예시
node_modules/
.env

등등...
```

2. Vercel 설치 및 로그인

배포를 위해서는 Vercel CLI를 설치하고, 계정에 로그인해야 합니다.

Vercel CLI 글로벌 설치

npm install -g vercelbash

또는 yarn global add vercel, pnpm add -g vercel , bun i -g vercel등 원하는 패키지 매니저를 사용해도 됩니다.

Vercel 계정으로 로그인

→ 미리 Vercel 사이트에 들어가 회원가입을 하시면 저와 같이 동일하게 진행하실 수 있습니다!

vercel loginbash

명령을 입력하면 다음과 같은 선택지가 나옵니다.

// 여러분들의 맞는 로그인 방식으로 진행해주시고
// 만약 계정이 없으시다면, 회원가입을 진행해주시면 됩니다.
// 저는 깃허브로 로그인 해서 해당 부분을 체크하겠습니다.
// 키보드 화살표 위 아래로 선택할 수 있습니다.
Vercel CLI 41.7.0
? Log in to Vercel (Use arrow keys)
❯ Continue with GitHub           // ✅
  Continue with GitLab
  Continue with Bitbucket
  Continue with Email
  Continue with SAML Single Sign-On

? Log in to Vercel Continue with GitHub
> Success! GitHub authentication complete for dydals3440@gmail.com // 여러분들 이메일
Congratulations! You are now logged in. In order to deploy something, run `vercel`.
💡  Connect your Git Repositories to deploy every branch push automatically (https://vercel.link/git).tsx

Continue with GitHub 등 여러분들이 만든 선택해 로그인 과정을 완료하세요.
로그인이 성공하면 “Success! GitHub authentication complete for your-email@example.com” 메시지가 표시됩니다.

3. 프로젝트 초기 설정 및 Preview 배포

이제 로컬 프로젝트를 Vercel에 연결하고, Preview 환경(미리보기)으로 배포해 보겠습니다.

vercel 명령어 실행

vercelshell

처음 실행하면 다음과 같이 묻습니다.

? Set up and deploy “~/deploy-vercel”? (Y/n) // Y 입력 후 Enter

기본값 Y를 그대로 사용하고 Enter를 누릅니다.

Scope(팀 또는 개인 사용자)를 선택

? Which scope should contain your project? (Use arrow keys)
❯ 여러분들아이디's projects                 // 파란글씨 Entertsx

개인 프로젝트라면 your-username’s projects를 선택합니다.

팀 프로젝트면 팀 프로젝트명을 선택하시면 됩니다.

기존 프로젝트와 연결할지 묻는 단계

// 여러분들은 지금 레포를 연결하지 않았으므로 N 후 Enter 입니다.
// 만약 레포지토리를 사이트를 통해서 미리 연결했으면 y를 진행 후 해당 레포지토리를 연결해주시면 됩니다.
? Link to existing project? (y/N)  // N 입력 후 Entertsx

GitHub에 미리 Vercel을 연동하지 않았으면 N을 입력하고 Enter를 누릅니다.
이미 프로젝트를 Vercel에 연결한 상태라면 y를 선택해 해당 레포지토리를 연결할 수 있습니다.

프로젝트 이름 입력

// ()안에있는게 기본 이름이고 바꾸고 싶으면 변경하셔도 좋습니다.
// 단 프로젝트 이름은 아래 조건이 맞아야 하니 유의해주세요
// Project names can be up to 100 characters long and must be lowercase. They can include letters, digits, and the following characters: '.', '_', '-'. However, they cannot contain the sequence '---'. (400)
? What’s your project’s name? (deploy-vercel)  // ohtani라고 저는 이름 변경후 Entertsx

기본값으로 제안되는 이름을 사용하거나, 영문 소문자, 숫자, ., _, 만 포함하도록 직접 지정할 수 있습니다.
프로젝트 이름은 최대 100자까지 가능하며, 연속으로 --은 포함할 수 없습니다.

코드가 위치한 디렉터리

// (./)는 현재 프로젝트 루트를의미합니다. 맞으니 Enter
? In which directory is your code located? ./tsx

보통 ./ 그대로 두고 Enter를 눌러 프로젝트 루트를 지정합니다.

자동 감지된 설정 확인

Vite, Next.js, Nuxt.js 등 특정 프레임워크라면 Vercel이 기본 빌드/실행 명령을 자동으로 감지해서 보여줍니다.

// 바꾸지 않을겁니다. N 입력 후 Enter
Local settings detected in vercel.json:
Auto-detected Project Settings (Vite):
- Build Command: vite build
- Development Command: vite --port $PORT
- Install Command: `yarn install`, `pnpm install`, `npm install`, or `bun install`
- Output Directory: dist
? Want to modify these settings? (y/N) // N 입력 후 Entertsx

별도 설정이 필요 없으면 N을 입력하고 Enter를 눌러 넘어갑니다.

Preview 환경 배포 완료

설정이 끝나면 아래와 같이 Preview(deploy preview) URL이 반환됩니다.

Vercel CLI 41.7.0
🔍  Inspect: https://vercel.com/dydals3440s-projects/ohtani/2V16YYxwLyp55YKZ2mQ7RfsfFSDG [2s]
✅  Preview: https://ohtani-r06wspu21-dydals3440s-projects.vercel.app [2s]
📝  To deploy to production (ohtani-seven.vercel.app), run `vercel --prod`

Preview: https://ohtani-r06wspu21-dydals3440s-projects.vercel.app 주소를 브라우저에 입력하면, 로그인된 Vercel 계정일 때만 실제 배포된 페이지를 확인할 수 있습니다.
주의: 아직 Production(실제 서비스) 환경이 아니기 때문에, 위 URL은 Vercel 인증을 거친 사용자만 접근이 가능합니다.

4. Production(실서비스) 배포

Preview 환경이 정상적으로 동작하는 것을 확인했다면, 이제 실제 서비스용 URL을 생성하기 위해 --prod 옵션을 사용합니다.

vercel --prodtsx

배포가 성공하면 콘솔에 다음과 같은 메시지가 나옵니다.

Vercel CLI 41.7.0
🔍  Inspect: https://vercel.com/your-username/projects/project-name/hijklmn67890 [800ms]
✅  Production: https://project-name-uvw456.vercel.app [800ms]

이제 실제 배포된 URL을 확인해보겠습니다.

vercel을 로그인 한 후, 여러분들의 대시보드 페이지로 와주시면 됩니다.

Deployments 탭에 들어가시면 여러분들이 Production에 이제 배포했음을 확인할 수 있습니다.

클릭해서 들어가보시면 Deployment Details를 아래와 같이 확인할 수 있습니다.

빨간색으로 밑줄 그은 URL을 통해 접속하시면
어떠한 기기에서도 자유롭게 만드신 사이트를 공유받을 수 있습니다!

5. 환경변수는 어떻게 넣어주나요??

프로젝트를 배포할 때, API 키나 비밀 토큰 같은 값을 코드에 직접 적어두면 보안상 위험해요.
그래서 이런 값들은 환경변수(Environment Variables)로 따로 관리하는 게 원칙이에요.

그러나 우리는 .env, .env.local과 같은 파일에 환경변수를 넣고 실제로 이를 깃허브에 올리지 않습니다. 그리고 실제로 환경변수를 활용하는 코드는 당연히 현재 배포된 사이트에서는 값을 알 수 없으니 동작하지 않겠죠.

우리 사이트에서 환경변수를 쓰는 코드가 아래와 같이 있다고 가정해봅시다.

// .env
VITE_API_URL=https://ohtani.example.comtsx

해당 환경변수를 만약 아래와 같이 사용하고 있다면

// src/libs/axiosClient.ts
import axios from 'axios';

const api = axios.create({
  // 배포된 사이트는 이 값을 알 수 없어요 ㅠㅠ
  baseURL: import.meta.env.VITE_API_URL,
  headers: {
    'Content-Type': 'application/json',
  },
});

export default api;tsx

당연히 모든 api 통신은 동작하지 않을 것 입니다.

Vercel에서는 프로젝트 설정에서 간단하게 환경변수를 등록하고, 코드에서 그 값을 사용할 수 있습니다.

대시보드로 간 후 여러분들의 프로젝트 명을 클릭해주세요 (ohtani)

첫번째. 프로젝트 명을 클릭해주세요
그 후 settings를 클릭해주세요.

두번째. 프로젝트 명을 클릭해주세요
Environment Variables 탭에서 여러분들의 환경변수 key와 value에 맞게 값을 넣어주셔도 되고 많은 경우 그냥 .env 파일자체를 첨부하셔도 좋습니다. 그 이후 save를 해주세요.

세번쨰. 환경 변수 첨부

vercel도 여러분이 반영한 키에 대해서 알아야하므로 Save후에 파란색 팝업이 나오는데 Redeploy를 눌러주시면 됩니다.

vercelshell

vercel --prodshell

혹시라도 못 누르셨다면 그냥 다시 명령어를 통해 배포를 진행해주셔도 상관없습니다.

6. 어.. 내 다른 페이지는 왜 안나오지..?

여러분들의 홈페이지는 보통 하나의 페이지만 있는 것이 아닌, 여러개의 페이지가 있을 겁니다.

예를들어 저의 개인 블로그 같은 경우는 여러개의 페이지가 존재합니다.

홈페이지 : https://www.yolog.co.kr/
블로그 상세 페이지: https://www.yolog.co.kr/post/2025-1st-review

정말 많은 페이지로 구성되어있습니다. 여러분들이 next.js나 astro, remix와 같은 SSR 기반 사이트를 만드셨다면 4번까지만 하셔도 충분히 배포가 되셨을 것이라고 믿어 의심치 않습니다.

하지만 지금 React와 같은 SPA 기반 웹사이트 같은 경우 보통은 react-router를 활용하거나, tanstack-router를 활용하여 여러개의 페이지를 구성하게 됩니다.

import { createBrowserRouter, RouterProvider } from 'react-router-dom';
import './App.css';
import HomePage from './pages/HomePage';
import BaseballPage from './pages/BaseballPage';

const router = createBrowserRouter([
  {
    path: '/',
    element: <HomePage />,
  },
  {
    path: '/baseball',
    element: <BaseballPage />,
  },
]);

function App() {
  return <RouterProvider router={router} />;
}

export default App;tsx

지금 제가 블로그 게시글 작성을 위해 만든 예제 사이트는 react-router-dom을 활용하여 두개의 경로로 접근할 수 있는 페이지로 구성되어있습니다.

실제로 배포 했을 떄 / 루트 경로의 홈페이지는 아래 이미지와 같이 의도한대로 잘 보이게 됩니다.

하지만 /baseball 페이지는 실제로 개발환경에서는 잘 보이나 배포된 환경에서는 보이지 않습니다.

이러한 문제가 발생하는 이유는 아래와 같습니다.

React, Vue 같은 SPA(Single Page Application)에서는 클라이언트 측 라우팅을 사용해 페이지를 이동합니다.

즉 사용자가 /baseball 페이지를 이동해도 실제로는 서버에 별도의 /baseball.html 파일이 있는 것이 아니라, 항상 index.html 하나를 로드하고, 자바스크립트가 URL에 따라 화면을 바꿔주는 구조입니다!!

(SPA의 동작 방식이죠!)

그런데 이것을 Vercel 같은 정적 호스팅 서비스에 배포를 하면 문제가 생깁니다.

🕵️‍♀️ 사건의 재구성

/로 접속 → 잘 동작
/baseball으로 직접 접속 (새로고침) → 404 에러

왜냐하면 서버는 /baseball 이라는 실제 파일이나 디렉토리를 찾으려다가 없으니까 404를 반환합니다.

SPA는 이러한 경우에도 무조건 index.html을 불러주고, 클라이언트 라우터가 화면을 다시 그려줘야 정상인데 서버가 이것을 모르니 문제가 됩니다.

✅ 해결 방법: vercel.json 설정

감사하게도 vercel은 이러한 부분을 쉽게 해결할 수 있도록 해결 방법을 공식문서에 제공해주었습니다.

프로젝트의 루트에 vercel.json 파일을 만들어줍니다.

그 후 정규표현식을 활용한 약간의 코드를 작성해줄 것입니다.

// vervcel.json
{
  "routes": [
    {
      "src": "/[^.]+",
      "dest": "/index.html",
      "status": 200
    }
  ]
}tsx

src: "/[^.]+"
👉 .(점)이 없는 경로를 모두 잡아요. 즉, /about, /contact 같은 경로는 잡히고, /favicon.ico, /bundle.js 같은 파일 요청은 무시해요.
dest: "/index.html"
👉 이렇게 걸린 경로는 전부 index.html을 반환해요.
status: 200
👉 정상 응답 상태로 보내줍니다.