npm run dev 오류 해결: Missing script dev, EADDRINUSE, Cannot find module 점검 순서

npm run dev 오류는 보통 프로젝트 실행 명령이 잘못되었거나, 개발 서버 포트가 이미 사용 중이거나, 필요한 모듈이 설치되지 않았을 때 발생합니다. 먼저 package.json의 scripts 항목을 확인하고, 그다음 포트 충돌과 의존성 설치 상태를 차례대로 점검하면 대부분의 원인을 좁힐 수 있습니다.

특히 GitHub에서 프로젝트를 내려받은 뒤 npm install까지는 끝났지만 npm run dev에서 막힌 상황이라면 오류 메시지를 그대로 읽는 것이 중요합니다. Missing script: "dev", EADDRINUSE, Cannot find module, command not found는 각각 확인해야 할 위치가 다릅니다.

npm run dev 오류는 package.json, 포트 충돌, 모듈 설치, Node 버전 순서로 나눠 확인하면 원인을 좁히기 쉽습니다.

npm run dev 오류 메시지 원문부터 확인하기

같은 npm run dev 오류처럼 보여도 원인은 서로 다를 수 있습니다. 터미널에 나온 마지막 한 줄만 보지 말고, 오류 메시지에서 핵심 문장을 먼저 찾아야 합니다.

오류 메시지	주요 원인	먼저 볼 곳
Missing script: "dev"	package.json에 dev 스크립트가 없음	scripts 항목
EADDRINUSE	개발 서버 포트가 이미 사용 중	3000, 5173, 8080 포트
Cannot find module	필요한 패키지 또는 파일을 찾지 못함	node_modules, import 경로
npm: command not found	Node.js 또는 npm 경로 문제	Node 설치, PATH, nvm 설정

npm run dev는 언제 쓰는 명령어일까

npm run dev는 npm이 package.json 안의 scripts에서 dev라는 이름의 명령을 찾아 실행하는 방식입니다. 즉, 모든 Node.js 프로젝트에서 자동으로 동작하는 고정 명령어가 아닙니다.

예를 들어 Vite 프로젝트라면 dev가 개발 서버 실행 명령으로 들어 있는 경우가 많지만, 어떤 프로젝트는 start, serve, local 같은 다른 이름을 쓸 수 있습니다. 그래서 오류가 났을 때 가장 먼저 봐야 할 파일은 터미널이 아니라 package.json입니다.

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}

Missing script: "dev" 원인과 해결

Missing script: "dev"는 npm이 현재 폴더의 package.json에서 dev라는 스크립트를 찾지 못했다는 뜻입니다. 이 경우에는 무작정 재설치하기보다 현재 위치와 스크립트 이름을 먼저 확인해야 합니다.

npm ERR! Missing script: "dev"
npm ERR!
npm ERR! To see a list of scripts, run:
npm ERR!   npm run

현재 폴더가 프로젝트 루트인지 확인하기

package.json이 있는 폴더에서 실행해야 npm 스크립트를 찾을 수 있습니다. 프로젝트 안에 frontend, client, app 같은 하위 폴더가 따로 있는 경우 루트가 다를 수 있습니다.

pwd
ls

# Windows PowerShell
Get-Location
dir

실제 스크립트 목록 확인하기

어떤 명령어가 준비되어 있는지 보려면 npm run만 입력합니다. 여기서 dev가 없고 start나 serve가 있다면 프로젝트 안내 문서에 맞춰 다른 명령을 실행해야 합니다.

npm run

dev 스크립트가 없는 경우

프로젝트 문서가 npm run dev를 요구하는데 package.json에 dev가 없다면 저장소 버전이 바뀌었거나, 예제 코드가 일부만 복사되었거나, 하위 폴더에서 실행해야 하는 구조일 수 있습니다. 이때는 스크립트를 임의로 추가하기 전에 README와 폴더 구조부터 확인합니다.

상황	확인할 것	예시
dev가 없고 start만 있음	실행 명령이 npm start인지 확인	npm start
하위 폴더에 package.json 있음	실제 앱 폴더로 이동	cd frontend
README와 scripts가 다름	저장소 브랜치와 최신 문서 확인	main, develop 비교

package.json scripts 확인 방법

package.json의 scripts는 프로젝트에서 자주 쓰는 명령어를 이름으로 묶어 둔 부분입니다. npm run dev는 이 목록 안에 "dev"가 있을 때만 실행됩니다.

{
  "name": "my-app",
  "version": "1.0.0",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  },
  "dependencies": {
    "next": "^15.0.0",
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  }
}

여기서 중요한 것은 dev 오른쪽의 실제 실행 명령입니다. vite, next dev, astro dev, node server.js처럼 프로젝트마다 다를 수 있습니다. 따라서 오류를 볼 때는 npm run dev만 보지 말고 그 안에서 실제로 실행되는 명령까지 확인해야 합니다.

EADDRINUSE 포트 충돌 해결

EADDRINUSE는 개발 서버가 사용하려는 포트를 다른 프로세스가 이미 쓰고 있다는 뜻입니다. React, Next.js, Vite 프로젝트에서는 3000, 5173, 8080 같은 포트에서 자주 발생합니다.

Error: listen EADDRINUSE: address already in use :::3000

해결 1: 기존 개발 서버 종료

이전에 켜 둔 터미널에서 개발 서버가 계속 실행 중일 수 있습니다. 터미널 창을 확인하고 실행 중인 서버에서 Ctrl + C를 눌러 종료한 뒤 다시 실행합니다.

Ctrl + C
npm run dev

해결 2: 사용 중인 포트 찾기

어떤 프로그램이 포트를 쓰고 있는지 확인한 뒤 종료할 수 있습니다. 운영체제마다 명령어가 다르므로 본인 환경에 맞는 명령만 사용합니다.

환경	포트 확인	종료 예시
macOS / Linux	lsof -i :3000	kill -9 PID
Windows PowerShell	netstat -ano | findstr :3000	taskkill /PID PID /F

해결 3: 다른 포트로 실행하기

기존 포트를 종료하기 어렵다면 개발 서버 포트를 바꿔 실행할 수 있습니다. 프레임워크마다 방식이 다르므로 프로젝트 문서와 package.json을 함께 확인합니다.

# Vite 예시
npm run dev -- --port 5174

# Next.js 예시
npm run dev -- -p 3001

Cannot find module 오류 해결

Cannot find module은 Node.js가 필요한 패키지나 파일을 찾지 못할 때 나옵니다. 설치가 빠졌거나, import 경로가 틀렸거나, 프로젝트의 Node 버전이 맞지 않을 때도 이어질 수 있습니다.

Error: Cannot find module 'vite'
Error: Cannot find module './src/app'
Module not found: Can't resolve 'react'

먼저 npm install을 다시 확인하기

GitHub에서 프로젝트를 처음 받은 상태라면 node_modules 폴더가 없는 것이 정상입니다. 이 경우에는 프로젝트 루트에서 의존성을 설치해야 합니다.

npm install
npm run dev

npm install 단계에서 이미 오류가 났다면 실행 오류가 아니라 설치 오류를 먼저 해결해야 합니다. EACCES, ERESOLVE, node-gyp처럼 설치 단계에서 발생한 문제는 원인이 다르므로 npm install 오류 해결 순서를 먼저 확인하는 편이 좋습니다.

패키지 이름과 import 경로 확인하기

Cannot find module './components/Button'처럼 상대 경로가 표시된다면 패키지 설치보다 파일 경로 문제일 수 있습니다. 파일 이름의 대소문자, 확장자, 이동된 폴더를 확인해야 합니다.

# macOS / Linux에서는 대소문자 차이가 문제 될 수 있음
import Button from './components/Button'

# 실제 파일명이 button.jsx라면 경로를 맞춰야 함
import Button from './components/button'

node_modules와 package-lock.json을 지울 때 주의점

검색 결과에서 자주 보이는 해결법 중 하나가 node_modules와 package-lock.json 삭제 후 재설치입니다. 이 방법은 설치 상태가 꼬였을 때 도움이 될 수 있지만, 항상 첫 번째 해결책은 아닙니다.

혼자 실습 중인 프로젝트이고 설치 상태가 꼬였다고 판단될 때만 아래 순서로 다시 설치합니다.

# macOS / Linux
rm -rf node_modules package-lock.json
npm install
npm run dev

# Windows PowerShell
Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json
npm install
npm run dev

Windows, Mac, Linux에서 다른 점

Node.js 프로젝트 실행 흐름은 비슷하지만 터미널 명령, 경로, 환경변수 설정 방식은 운영체제마다 다릅니다. 특히 강의나 문서가 macOS 기준으로 작성되어 있는데 Windows PowerShell에서 그대로 따라 하면 명령어가 실패할 수 있습니다.

구분	자주 다른 부분	확인 방법
Windows	PowerShell 명령, PATH, 관리자 권한	node -v, npm -v, where npm
macOS	nvm, Homebrew, zsh PATH 충돌	which node, which npm
Linux	권한, 배포판 패키지 버전, 포트 사용	node -v, npm -v, lsof -i

VSCode 터미널에서 확인할 것

일반 터미널에서는 되는데 VSCode 터미널에서만 npm run dev가 안 된다면 프로젝트 문제가 아니라 VSCode 터미널 환경 문제일 수 있습니다. 특히 nvm으로 Node 버전을 관리하는 경우 새 터미널을 열기 전 설정이 반영되지 않는 경우가 있습니다.

node -v
npm -v
npm run

VSCode 터미널에서 npm: command not found가 나오거나 Node 버전이 다르게 잡힌다면 터미널 종류, PATH, nvm 초기화 설정을 확인해야 합니다. 이 경우에는 VSCode 터미널 command not found 해결 순서를 함께 보면 원인을 더 빨리 좁힐 수 있습니다.

재발 방지 체크리스트

개발 서버 실행 오류는 한 번 해결해도 프로젝트를 바꾸거나 터미널을 바꾸면 다시 생길 수 있습니다. 아래 항목을 습관처럼 확인하면 같은 오류를 줄일 수 있습니다.

공식 자료로 더 확인하기

npm 스크립트와 Node.js 오류는 프로젝트마다 출력이 조금씩 다를 수 있습니다. 정확한 의미는 공식 문서의 기준과 현재 프로젝트의 package.json을 함께 대조해 확인합니다.

함께 보면 좋은 글

자주 묻는 질문

npm run dev 오류는 오류 메시지를 먼저 나누고, package.json scripts, 포트 충돌, 의존성 설치, Node 버전 순서로 확인하는 것이 가장 빠릅니다.