Vercel API 함수에서만 'Cannot Find Module' 오류 발생

(dev.to)

Vercel API 함수 배포 시 발생하는 'Cannot Find Module' 오류는 프론트엔드 번들러와 서버리스 함수의 개별 배포 방식 차이로 인해 발생하며, 이를 해결하기 위해서는 API 경로 내 상대 경로 임포트에 명시적인 확장자를 추가해야 합니다.

이 글의 핵심 포인트

1Vercel API 함수 배포 시 확장자 없는 상대 경로 임포트로 인해 'Cannot Find Module' 오류 발생
2moduleResolution: "Bundler" 설정은 Vite 번들링 환경에서는 유효하지만, 개별 배포되는 API 함수에는 적용되지 않음
3@vercel/node는 API 파일을 번들링 없이 개별 서버리스 함수로 배포하여 Node.js ESM 로더의 영향을 받음
4해결책은 api/ 디렉토리 내의 모든 상대 경로 임포트에 .js 확장자를 명시적으로 추가하는 것
5TypeScript 소스 파일은 .ts를 유지하되, 임포트 문에는 컴파일 후 결과물인 .js를 사용해야 함

이 글에 대한 공공지능 분석

왜 중요한가?

개발 환경과 운영 환경의 불일치(Environment Mismatch)가 어떻게 빌드 성공 후 런타임 장애로 이어지는지 보여주는 전형적인 사례이기 때문입니다. 특히 자동화된 테스트나 빌드 파이프라인이 잡아내지 못하는 사각지대를 식별하는 데 매우 중요한 교훈을 줍니다.

어떤 배경과 맥락이 있나?

최신 프론트엔드 개발은 Vite와 같은 번들러를 통해 확장자 생략을 허용하는 'Bundler' 모드를 사용하지만, Vercel의 @vercel/node는 API 파일을 번들링 없이 개별 서버리스 함수로 배포합니다. 이 과정에서 Node.js의 ESM(ES Modules) 표준 준수 여부가 충돌을 일으킵니다.

업계에 어떤 영향을 주나?

서버리스 아키텍처를 채택하는 팀은 번들러(Vite)와 런타임(Node.js)의 동작 차이를 명확히 이해해야 하며, 이는 CI/CD 파이프라인 설계 시 단순 빌드 성공 여부뿐만 아니라 런타임 환경의 정합성 검증이 필요함을 시사합니다.

한국 시장에 어떤 시사점이 있나?

빠른 배포와 효율성을 중시하는 한국 스타트업들에게, 프레임워크의 편리함 뒤에 숨겨진 인프라적 특성을 간과할 경우 서비스 런칭 직후 치명적인 장애를 겪을 수 있음을 경고합니다.

이 글에 대한 큐레이터 의견

이 사례는 '개발 편의성'과 '런타임 안정성' 사이의 트레이드오프를 극명하게 보여줍니다. `moduleResolution: "Bundler"` 설정은 개발 생산성을 높여주지만, 인프라의 배포 메커니즘을 고려하지 않은 설정은 결국 운영 환경에서의 장애로 이어집니다. 개발자는 번들러가 제공하는 추상화된 편리함에 안주하기보다, 실제 코드가 실행되는 런타임 환경의 제약 사항을 깊이 있게 이해해야 합니다.

물론, 모든 임포트에 확장자를 붙이는 방식은 코드의 가독성을 떨어뜨리고 번들러 중심의 현대적 개발 흐름에 역행하는 것처럼 보일 수 있습니다. 하지만 서버리스 환경에서는 이 작은 수고가 서비스 가용성을 결정짓는 핵심 요소가 됩니다. 따라서 스타트업 창업자와 리드 개발자는 기술 스택을 도입할 때, 단순히 '편리한 도구'를 찾는 것을 넘어 '우리 서비스의 배포 및 실행 아키텍처와 완벽히 호환되는지'를 검증하는 프로세스를 반드시 구축해야 합니다.

원문 보기 →