Blog | 김대성의 블로그

블로그를 만들자마자 트러블 슈팅을 작성할 줄은 몰랐습니다.

문제 상황

Vercel에서 Astro 프로젝트를 빌드하는 중 에러 발생

[ImageNotFound] [commonjs--resolver] Could not find requested image `../../assets/projects/PICA/PICA_Icon.webp`. Does it exist?

로컬에서는 정상적으로 빌드되고 실행되었지만, Vercel의 Linux 빌드 환경에서는 이미지 파일을 찾지 못했습니다.

원인 분석

1. 파일 시스템의 대소문자 구분 차이

Windows: 파일명과 폴더명의 대소문자를 구분하지 않음
- PICA와 pica를 동일하게 인식
Linux (Vercel 빌드 환경): 대소문자를 엄격하게 구분함
- PICA와 pica를 완전히 다른 경로로 인식

2. Git 저장소의 실제 상태

Git에서 실제로 저장된 파일명과 폴더명을 확인한 결과

# Git에 저장된 실제 경로 (소문자)
src/content/project/pica.mdx
src/assets/projects/pica/PICA_Icon.webp

하지만 Windows 파일 탐색기에서는 대문자로 표시되어 있었습니다.

3. 코드에서 경로 참조

PICA.mdx 파일에서 대문자 경로를 사용하고 있었습니다.

thumbnail: '../../assets/projects/PICA/PICA_Icon.webp'
heroImage: '../../assets/projects/PICA/PICA_Hero.webp'

로컬 Windows 환경에서는 대소문자를 구분하지 않아 정상 작동했지만, Linux 빌드 환경에서는 실제로 존재하지 않는 경로(PICA)를 참조하여 에러가 발생했습니다.

해결 방법

Git에 저장된 실제 경로(소문자)에 맞춰 코드를 수정했습니다.

// 수정 전
thumbnail: '../../assets/projects/PICA/PICA_Icon.webp'
heroImage: '../../assets/projects/PICA/PICA_Hero.webp'
import screen1 from '../../assets/projects/PICA/PICA_Screen1.gif';

// 수정 후
thumbnail: '../../assets/projects/pica/PICA_Icon.webp'
heroImage: '../../assets/projects/pica/PICA_Hero.webp'
import screen1 from '../../assets/projects/pica/PICA_Screen1.gif';

배운 점

크로스 플랫폼 개발 시 주의사항
- Windows에서 개발하더라도 배포 환경이 Linux인 경우 대소문자 구분 등을 고려해야 함
- 파일명과 경로는 일관되게 사용하는 것이 중요함
빌드 환경 차이 고려
- 로컬에서 정상 작동한다고 해서 배포 환경에서도 동일하게 작동한다는 보장은 없음
- 가능하면 배포 환경과 유사한 환경에서 테스트하는 것이 좋음

예방 방법

프로젝트 초기에 파일명과 폴더명의 대소문자 규칙을 정하고 일관되게 적용
로컬 빌드뿐만 아니라 CI 환경에서도 빌드 테스트 수행
자주 사용하는 경로는 상수로 관리하여 일관성 유지

Vercel 빌드 에러 : 대소문자 경로 문제 해결