Next.js가 삭제된 파일을 계속 참조하는 문제 (.next 캐시 삭제 방법)

프로젝트에서 페이지를 정리하면서 특정 파일을 삭제했는데, 이후 TypeScript typecheck가 계속 실패하는 문제가 발생했다. 에러 메시지를 보니 이미 삭제한 파일을 여전히 참조하고 있었다. 실제 소스에는 해당 파일이 없는데도 빌드나 typecheck에서 계속 문제가 발생했다.

원인은 Next.js가 생성하는 타입 캐시와 빌드 아티팩트였다. 특히 .next 디렉토리에 남아 있는 타입 파일이 삭제된 페이지를 계속 참조하고 있었고, tsc가 해당 파일을 참조하려고 시도하면서 문제가 발생했다.

---

문제 원인 - Next.js 빌드 시

Next.js는 빌드 과정에서 .next 디렉토리에 빌드 아티팩트, 라우팅 정보, 타입 관련 파일, 캐시 데이터 등 파일들을 생성한다.

특히 최근 Next.js에서는 .next/types 내에 라우팅 관련 타입 파일이 생성된다. 이 파일들이 이전 상태를 기반으로 만들어지기 때문에, 다음과 같은 상황이 발생할 수 있다:

1. 페이지 파일 삭제
2. 실제 소스에서는 제거됨
3. 하지만 .next/types 안에는 이전 참조가 남아 있음
4. TypeScript가 해당 파일을 읽음
5. 존재하지 않는 경로를 참조하면서 에러 발생

즉 소스코드는 최신 상태인데 빌드 캐시는 과거 상태인 상황이다.

---

내가 겪은 문제

1. 특정 페이지 또는 컴포넌트 삭제
2. 이후 typecheck 실패
3. 에러 메시지에 삭제된 파일 경로 등장
4. 레포에는 해당 파일이 존재하지 않음
5. .next 내부 타입 파일에서 참조 발견

---

레포에 남은 참조가 있는지 검색

삭제한 파일이 실제로 완전히 제거됐는지 먼저 확인해보자.

git grep -n "componentTest" || true

이 커맨드는 레포 전체에서 해당 문자열을 찾는다.

여기서 아무것도 나오지 않으면 소스는 깨끗한 상태이며, 문제는 캐시에 있을 가능성이 크다.

---

해결 방법

Next.js가 만든 캐시와 타입 파일을 제거한다.

먼저 타입 캐시를 제거한다.

rm -rf apps/store/.next/types

문제가 계속된다면 더 확실하게 .next 전체를 제거해준다.

rm -rf apps/store/.next

그 다음 Next.js를 다시 빌드해서 타입을 재생성한다.

npx nx run store:build

또는

npx next build apps/store

마지막으로 typecheck를 다시 실행한다.

npx nx run store:typecheck

 

---

재발 방지 방법

1. 브랜치 이동 후 .next 정리
2. 대규모 파일 삭제 후 clean build
3. CI에서 clean build 사용
4. typecheck 실패 시 .next 확인

개인적으로는 다음 명령을 기억해두는 것이 가장 도움이 됐다.

rm -rf .next

 Next.js 프로젝트에서 이상한 타입 에러가 발생하면 캐시 문제를 의심해봐야 할 것 같다..