Blog

🚨 도입부

Node.js 개발자라면 누구나 한 번쯤은 ‘Error: Cannot find module’ 에러를 마주쳤을 것입니다. 이 에러는 프로젝트를 막 시작한 신입 개발자부터 복잡한 애플리케이션을 운영하는 베테랑 개발자까지 좌절하게 만들 수 있습니다. 특히, 프로젝트를 배포하거나 새로운 모듈을 설치한 후 발생할 때는 더욱 당황스럽습니다. 예를 들어, 새로운 패키지를 설치한 후 서버를 실행했는데 갑자기 모듈을 찾을 수 없다는 메시지가 뜨는 상황, 배포 후 환경에서만 발생하는 모듈 찾기 실패, 잘 동작하던 코드가 갑자기 모듈을 찾지 못하는 경우 등 다양한 시나리오에서 이 에러가 발생할 수 있습니다.

이 글에서는 이러한 문제를 해결하기 위한 구체적인 방법을 제공합니다. 빠르게 문제를 해결할 수 있는 즉시 적용 가능한 방법부터, 환경 설정을 통한 안정적인 해결법, 그리고 복잡한 상황을 위한 고급 해결법까지 단계별로 안내합니다. 에러를 해결하는 데 걸리는 시간은 상황에 따라 다르지만, 이 가이드를 따르면 보통 10분 내에 문제를 해결할 수 있을 것입니다. 난이도는 초보자도 충분히 따라할 수 있도록 구성하였습니다.

🔍 에러 메시지 상세 분석

‘Error: Cannot find module’은 Node.js가 특정 모듈을 찾지 못할 때 발생하는 오류 메시지입니다. 이 메시지는 ‘Error: Cannot find module ‘myModule”처럼 모듈 이름과 함께 나타날 수 있습니다. 이러한 에러는 다양한 상황에서 발생합니다. 첫째, 모듈이 제대로 설치되지 않았거나, 둘째, 설치 경로가 잘못되었거나, 셋째, 파일 경로를 잘못 지정했을 때, 넷째, package.json에 잘못된 설정이 있을 때, 다섯째, NODE_PATH 환경 변수가 잘못 설정되었을 때 발생할 수 있습니다.

메시지의 각 부분을 해석해보면, ‘Error’는 문제가 발생했음을 알리고, ‘Cannot find module’은 Node.js가 특정 모듈을 찾지 못했다는 것을 의미합니다. 초보자를 위한 팁으로, 에러 메시지가 발생한 위치와 모듈 이름을 주의 깊게 읽어보는 것이 중요합니다. 이 에러는 ‘MODULE_NOT_FOUND’와 같이 비슷한 다른 에러와 혼동될 수 있습니다. 그러나 ‘MODULE_NOT_FOUND’는 좀 더 구체적인 에러 코드로, 동일한 상황에서 발생할 수 있지만 메시지 형식이 다릅니다.

🧐 발생 원인 분석

이 에러의 주요 원인을 살펴보면 다음과 같습니다. 첫째, 모듈 설치의 누락입니다. npm install을 통해 모듈을 설치하지 않았거나, 설치가 도중에 실패했을 수 있습니다. 둘째, 파일 경로의 오류입니다. 모듈을 불러올 때 상대 경로나 절대 경로를 잘못 지정했을 수 있습니다. 셋째, NODE_PATH 환경 변수의 잘못된 설정입니다. 이 변수에 설정된 경로가 잘못되면 모듈을 찾지 못할 수 있습니다. 넷째, package.json 파일에 잘못된 설정이 포함되어 있을 수 있습니다. 다섯째, 로컬 모듈을 불러오는 과정에서 경로 설정이 잘못되었을 수 있습니다.

각 원인별로 발생 시나리오를 살펴보겠습니다. 모듈 설치 누락은 새로운 모듈을 설치한 후 npm install 명령을 실행하지 않았을 때 발생할 수 있습니다. 파일 경로 오류는 코드에서 require(‘./myModule’)를 사용하는데 실제 파일이 다른 디렉토리에 위치한 경우입니다. NODE_PATH 설정 오류는 운영체제나 버전별로 경로 설정이 달라져 발생할 수 있습니다. package.json의 오류는 dependencies나 devDependencies에 잘못된 모듈 이름을 지정했을 때 발생합니다.

개발 환경에 따라 이 문제는 다르게 나타날 수 있습니다. Windows에서는 파일 경로의 대소문자 문제로, Linux에서는 환경 변수 설정 문제로, macOS에서는 파일 시스템의 차이로 인한 경로 문제로 나타날 수 있습니다. 각 원인별 간단한 확인 방법으로는 모듈 설치 여부를 확인하거나, 파일 경로를 다시 한 번 체크해보는 것이 있습니다.

✅ 해결 방법

즉시 해결할 수 있는 방법으로는 세 가지가 있습니다. 첫째, 모듈을 다시 설치합니다. 터미널에서 npm install 모듈이름을 실행하여 필요한 모듈을 설치합니다. 둘째, 파일 경로를 확인합니다. 코드를 살펴보고 require 문에서 사용하는 경로가 올바른지 확인합니다. 셋째, 캐시를 정리합니다. npm cache clean --force 명령을 사용하여 npm 캐시를 정리합니다.

// 에러 발생 코드 예제
const myModule = require('./myModule');
console.log(myModule);

표준 해결법으로는 다음과 같은 방법이 있습니다. 첫째, package.json을 확인하여 dependencies가 올바르게 설정되었는지 확인합니다. 둘째, NODE_PATH 환경 변수를 올바르게 설정합니다. 셋째, 파일 경로를 절대 경로로 변경하여 사용하는 방법도 있습니다. 넷째, 모듈을 전역으로 설치한 경우 로컬로 다시 설치해봅니다. 다섯째, 프로젝트 내 다른 모듈과 경로 충돌이 없는지 확인합니다.

// 올바른 코드 예제
const path = require('path');
const myModule = require(path.resolve(__dirname, 'myModule'));
console.log(myModule);

고급 해결법으로는 모듈 번들링 도구를 사용하는 방법이 있습니다. 웹팩(Webpack)이나 롤업(Rollup) 같은 도구를 사용하면 모듈 경로 문제를 해결할 수 있습니다. 또한, TypeScript를 사용하여 타입 정의 파일을 통해 모듈 경로를 명확히 지정하는 방법도 있습니다. 마지막으로, Docker와 같은 컨테이너 환경을 사용하여 의존성을 격리할 수도 있습니다.

🛡️ 예방법 및 베스트 프랙티스

이 에러가 재발하지 않도록 하기 위한 방법으로는, 프로젝트 초기 설정 시 .editorconfig나 .eslint 파일을 설정하여 경로 규칙을 명확히 하는 것이 중요합니다. 또한, 패키지를 설치할 때는 항상 npm ci 명령을 사용하여 package-lock.json 파일을 기반으로 설치하는 것이 좋습니다. 팀 개발에서는 코드 리뷰 시 경로 설정을 주의 깊게 검토하고, 공통 모듈을 사용할 때는 별도의 모듈로 관리하는 것도 좋은 방법입니다.

// 예방을 위한 코드 패턴
const myModule = require('./myModule');
if (!myModule) {
    throw new Error('Module not found');
}

관련 문서화 방법으로는 프로젝트 내 README.md 파일에 모듈 설치 및 경로 설정 방법을 명시하고, 자주 발생하는 오류와 해결책을 기록하는 것도 도움이 됩니다.

🎯 마무리 및 추가 팁

이 글에서 다룬 내용을 요약하면 다음과 같습니다. 첫째, ‘Error: Cannot find module’ 에러는 잘못된 경로나 모듈 설치 누락으로 발생할 수 있습니다. 둘째, 다양한 해결 방법을 통해 문제를 신속하게 해결할 수 있습니다. 셋째, 예방책을 통해 에러 재발을 방지할 수 있습니다. 비슷한 에러로는 ‘MODULE_NOT_FOUND’가 있으며, 이를 해결하기 위한 다른 글도 참고하시기 바랍니다.

추가 학습 리소스로는 Node.js 공식 문서나 MDN 웹 문서를 추천합니다. 마지막으로, 문제를 해결해 나가는 과정에서 좌절하지 마시고, 하나하나 해결해 나가는 성취감을 느껴보시기 바랍니다. 함께 해결해 나갈 수 있습니다!