Vercel로 포트폴리오 배포하며 겪은 이미지 깨짐 이슈 해결기

최근에 제작한 포트폴리오 웹사이트를 실제 이력서 제출용으로 사용하기 위해 Vercel로 배포했다. 배포 자체는 어렵지 않았지만, 배포 이후에 이미지와 비디오가 로드되지 않는 문제가 발생했고, 이 글에서는 그 과정을 정리하고 해결 방법을 공유한다.

🔧 Vercel을 선택한 이유

• 정적 사이트 배포에 최적화: React, Vite, Next.js와 잘 맞는다.

• GitHub 연동이 쉬움: main 브랜치만 올려두면 자동 배포된다.

• 무료 플랜도 충분: 개인 프로젝트나 포트폴리오에는 매우 적합하다.

🚀 기본 배포 흐름

1. GitHub에 프로젝트 업로드

2. Vercel에서 새 프로젝트 추가

3. GitHub 연동 및 main 브랜치 선택

4. 자동 배포 진행

문제는 배포 후 발생했다.

❌ 이미지와 비디오가 깨졌다?

배포 후 블로그 카드에 썸네일 이미지가 로드되지 않고 "엑스박스"가 표시되기 시작했다. 비디오 역시 마찬가지로 로딩 실패.

내가 처음 사용했던 경로는 다음과 같았다:

thumbnail: "/src/assets/image/thumbnail_chop.png"

이 코드는 개발 환경에서는 잘 작동했지만, Vercel로 배포한 후에는 동작하지 않았다.

🧩 원인 분석

Vite, Vercel에서는 public/ 폴더만이 정적 자산으로 처리되고, /src/assets는 빌드시 번들링되어 상대경로가 깨진다.

✅ 해결 방법: public 경로로 옮기기

이미지를 /public/assets/image/로 이동

• 경로를 다음처럼 수정:

thumbnail: "/assets/image/thumbnail_chop.png"

커밋 후 Vercel에서 자동 재배포 확인

이미지 및 비디오 로드 문제 해결 🎉

🛑 GitHub raw 링크는 대안일까?

처음엔 GitHub raw URL을 다음과 같이 활용해봤다:

thumbnail: "https://github.com/user/repo/blob/main/public/assets/image/img.png?raw=true"

하지만 이 방법은 성능상 비효율적이고, 깃허브 의존성이 생긴다. 되도록 public/ 폴더에 정적 파일을 관리하는 것이 안정적이다.

🧠 배운 점

정적 자산은 꼭 public/ 폴더에 넣자

빌드 후 상대 경로는 깨질 수 있다

개발 환경에서 된다고 방심하지 말 것

커밋만 해도 Vercel에서 자동 배포되니 관리가 간편

📝 마무리

이번 과정을 통해 정적 자산 관리의 중요성과 배포 환경에서 발생하는 미묘한 이슈들을 경험할 수 있었다. 단순히 작동하는 것에서 멈추는 게 아니라, 사용자에게 안정적으로 보여지는 것이 진짜 완성이라는 걸 다시금 느꼈다.