Vercel 빌드에서 next: command not found가 났을 때

GitHub 저장소를 Vercel에 연결하고 첫 배포를 돌렸을 때, 빌드 로그에는 next 명령을 찾을 수 없다는 메시지가 나왔다. 코드가 크게 잘못된 것처럼 보였지만, 실제 원인은 앱 위치와 설치 위치를 Vercel이 제대로 이해하지 못한 데 가까웠다.

Tangly는 루트에 모바일과 웹이 같이 있는 구조다. 웹 앱은 apps/web 아래에 있고, 실제 Next.js 의존성도 그쪽 package.json 안에서 관리된다. 그런데 Vercel이 루트를 기준으로 빌드를 해버리면 next 실행 파일을 못 찾을 수 있다.

먼저 빌드 로그에서 어떤 명령이 실행되는지 봤다. npm run build가 어디에서 실행되고, 그 안에서 어떤 스크립트가 호출되는지가 중요했다.

그다음 Vercel 프로젝트의 Root Directory를 apps/web으로 맞췄다. 이 설정이 맞아야 Vercel이 웹 앱의 package.json, dependencies, next.config를 기준으로 설치와 빌드를 진행한다.

마지막으로 Framework Preset과 Build Command가 과하게 꼬이지 않았는지 확인했다. 자동 감지가 어긋난 상태에서는 필요한 값만 명시적으로 저장하고 다시 배포했다.

모노레포에서는 에러 메시지가 코드 문제처럼 보여도 실제로는 작업 디렉터리 문제일 수 있다. 특히 command not found류 에러는 의존성이 없는 것이 아니라, 의존성이 있는 위치에서 명령을 실행하지 않은 경우가 많다.

앞으로 배포 문제가 생기면 먼저 로그의 현재 위치, 설치 위치, 실행 명령을 확인하기로 했다. 이 세 가지를 보면 꽤 많은 배포 실패를 빠르게 좁힐 수 있다.