Vercel Module not found, 재설치 실수 막는 대소문자 3분 점검

로컬에서는 npm run build가 통과했는데 Vercel 배포에서만 Module not found가 뜨면, 초보자는 보통 패키지부터 다시 깔려고 합니다. 하지만 오류 줄에 @/components/Button, ../components/header처럼 파일 경로가 보인다면 재설치보다 파일명 대소문자 확인이 먼저입니다. 특히 Windows나 macOS에서 만든 프로젝트를 Linux 기반 배포 환경으로 올릴 때 이 차이가 드러날 수 있습니다.

로컬에서는 통과하지만 배포 환경에서 파일명 대소문자 차이로 실패하는 흐름

vercel.com의 Module not found 안내는 일부 파일 시스템이 대소문자를 엄격히 구분하지 않지만 Vercel 배포는 대소문자를 구분하는 파일 시스템을 사용한다고 설명합니다. nextjs.org의 오류 문서도 원인 중 하나로 "import하려는 모듈의 대소문자가 다름"을 듭니다. 따라서 이 글의 목표는 하나입니다. 패키지 문제로 단정하기 전에 경로 대소문자를 3분 안에 분리하는 것입니다.

1분째에는 빌드 로그에서 못 찾은 경로만 떼어냅니다

Vercel 로그 전체를 처음부터 읽으려 하면 눈이 흐려집니다. 먼저 Module not found, Can't resolve, Cannot find module이 있는 줄만 찾습니다. 이 줄에는 보통 실패한 파일과 찾지 못한 경로가 함께 나옵니다.

Module not found: Can't resolve '@/components/Header'
./src/app/page.tsx:3:1

여기서 중요한 값은 두 개입니다. 하나는 page.tsx처럼 import를 쓴 파일이고, 다른 하나는 @/components/Header처럼 찾지 못한 경로입니다. 이 두 값을 메모하면 됩니다. 아직 npm install을 다시 하지 않습니다. 오류가 패키지 누락이면 패키지 이름이 보일 때가 많지만, 지금처럼 프로젝트 내부 경로가 보이면 내 파일명과 import 경로가 같은지가 먼저입니다.

AI에게 물을 때도 "Vercel 배포가 실패했어요"라고만 쓰지 말고 로그의 해당 줄을 그대로 줍니다. 오류 줄을 잘라 주면 AI가 원인을 추측하는 범위가 줄어듭니다.

2분째에는 실제 파일명과 import 경로를 한 글자씩 비교합니다

다음은 로컬 파일 탐색기나 에디터에서 실제 파일명을 봅니다. 예를 들어 실제 파일이 src/components/header.tsx인데 코드에는 이렇게 되어 있을 수 있습니다.

import Header from "@/components/Header";

사람 눈에는 같은 파일처럼 보이지만 header.tsx와 Header.tsx는 배포 환경에서 다른 이름으로 취급될 수 있습니다. 반대로 실제 파일은 Button.tsx인데 import가 button으로 되어 있을 수도 있습니다. 이때 고칠 대상은 보통 둘 중 하나입니다.

확인 지점	볼 것	판단
실제 파일명	`Header.tsx`인지 `header.tsx`인지	팀 규칙에 맞는 이름으로 정리
import 경로	코드에서 쓴 대소문자	실제 파일명과 완전히 일치
폴더명	`components`인지 `Components`인지	폴더도 대소문자 비교

이 단계에서 파일명과 import 경로가 완전히 같아질 때까지 한쪽만 고칩니다. 파일을 여러 개 옮기거나 폴더 구조를 다시 짜면 문제가 커집니다.

3분째에는 Git이 대소문자 변경을 추적했는지 확인합니다

문제는 여기서 한 번 더 생깁니다. 로컬 파일 시스템이 대소문자 차이를 느슨하게 다루면, Git이 header.tsx에서 Header.tsx로 바꾼 일을 제대로 변경으로 안 잡는 경우가 있습니다. git-scm.com의 core.ignoreCase 설명도 대소문자를 구분하지 않는 파일 시스템에서 Git이 보정 동작을 한다고 설명합니다.

먼저 상태를 봅니다.

git status
git ls-files | grep -i "header"

Windows PowerShell이라면 이렇게 볼 수 있습니다.

git ls-files | Select-String -Pattern "header"

여기서 Git이 추적하는 이름이 실제로 원하는 대소문자인지 봅니다. 예를 들어 로컬 파일은 Header.tsx인데 git ls-files에는 src/components/header.tsx로 남아 있으면, 배포 서버는 예전 이름을 기준으로 받을 수 있습니다.

안전한 방식은 Git에게 이름 변경을 명확히 알려 주는 것입니다. 대소문자만 바꾸는 rename이 애매하면 중간 이름을 한 번 거칩니다.

git mv src/components/header.tsx src/components/header-temp.tsx
git mv src/components/header-temp.tsx src/components/Header.tsx
git commit -m "fix: match component filename casing"

git-scm.com의 git mv 문서는 파일이나 디렉터리를 이동 또는 이름 변경하는 명령이며, 성공하면 index가 갱신된다고 설명합니다. 그래서 파일명 대소문자 문제는 에디터에서 이름만 바꾸는 것보다 git mv로 기록을 남기는 편이 안전합니다.

Vercel Module not found에서 재설치 전에 확인할 5단계 점검표

AI에게는 해결 명령보다 판단 자료를 먼저 줍니다

AI에게 "고쳐줘"라고만 말하면 npm install, 경로 별칭 수정, tsconfig 수정, 파일 이동을 한꺼번에 제안할 수 있습니다. 지금은 범위를 좁혀야 합니다. 아래 프롬프트를 그대로 채워 넣습니다.

상황:
로컬에서는 빌드가 되는데 Vercel 배포에서만 Module not found가 납니다.

Vercel 오류 줄:
[Module not found 또는 Can't resolve가 있는 줄 붙여넣기]

실제 파일명:
[에디터 또는 파일 탐색기에서 본 실제 경로]

코드의 import:
[문제가 난 import 한 줄]

Git 추적 이름:
[git ls-files로 확인한 경로]

요청:
패키지 재설치나 폴더 재구성 전에, 파일명 대소문자 불일치 가능성만 먼저 판단해 주세요.
고칠 파일과 바꿀 import 경로를 하나씩만 제안해 주세요.

이 프롬프트의 핵심은 바로 실행할 명령이 아니라 비교할 증거를 먼저 주는 것입니다. AI가 만든 코드일수록 변경 범위가 커지기 쉽습니다. 그래서 이번 오류에서는 원인 후보를 대소문자, 실제 파일 위치, Git 추적 이름으로 제한해야 합니다.

그래도 안 되면 패키지 누락과 경로 별칭을 그다음에 봅니다

대소문자가 맞고 Git 추적 이름도 맞는데 오류가 계속되면 그때 다른 원인을 봅니다. Next.js 문서는 Module not found의 원인으로 설치되지 않은 의존성, 다른 디렉터리, 대소문자 차이, Node.js 전용 모듈 사용 등을 함께 설명합니다. 따라서 대소문자 문제가 아니라고 확인한 뒤에는 다음 순서로 좁히면 됩니다.

오류 경로가 swr, axios처럼 외부 패키지 이름인지 봅니다.
외부 패키지라면 package.json의 dependencies에 있는지 봅니다.
@/ 같은 경로 별칭을 썼다면 tsconfig.json의 paths와 실제 폴더를 비교합니다.
서버 전용 코드를 클라이언트 컴포넌트에서 import했는지 봅니다.

하지만 처음부터 네 가지를 다 만지면 배포 실패 원인을 잃습니다. 오늘은 먼저 Module not found 한 줄, 실제 파일명, import 경로, Git 추적 이름만 확인합니다. 이 네 가지가 맞으면 그다음 원인으로 넘어가도 늦지 않습니다.

환경별 값 때문에 배포에서만 문제가 난다면 Next.js 환경변수의 이름과 위치를 비교하는 순서를 이어서 확인하세요. 배포는 됐지만 이전 화면이 남는다면 Vercel 브랜치와 캐시를 확인하는 순서가 다음 점검입니다.

참고 출처

Vercel Knowledge Base, How do I resolve a 'module not found' error?: https://vercel.com/kb/guide/how-do-i-resolve-a-module-not-found-error
Next.js Docs, Module Not Found: https://nextjs.org/docs/messages/module-not-found
Git Documentation, git-config core.ignoreCase: https://git-scm.com/docs/git-config
Git Documentation, git-mv: https://git-scm.com/docs/git-mv

이 글은 AI 코딩과 개발 학습의 일반 정보 제공 목적입니다. 도구, 모델, 커리큘럼, 요금은 버전과 시점에 따라 달라질 수 있으므로 실습이나 도입 전 공식 문서와 최신 릴리스 노트를 확인하세요.