npm run dev가 missing script로 멈출 때 package.json scripts부터 확인하는 법

npm run dev를 쳤는데 터미널에 Missing script: "dev"가 나오면 초보자는 보통 두 가지를 동시에 걱정합니다. 하나는 앱이 망가졌다는 생각이고, 다른 하나는 AI가 만든 코드 전체를 다시 고쳐야 한다는 생각입니다. 하지만 이 오류는 먼저 코드 오류가 아니라 실행 명령 이름 문제로 봐야 합니다.

npm run-script 문서는 npm run-script가 package.json의 scripts 객체에 있는 명령을 실행한다고 설명합니다. 짧게 쓰면 npm run <이름>입니다. 그러므로 npm run dev가 실패했다는 말은 일단 scripts 안에 dev라는 이름이 없다는 뜻에 가깝습니다. 삭제나 재설치보다 먼저 볼 곳은 package.json의 scripts 블록입니다.

Tap to zoom

터미널 오류 한 줄에서 문제 범위를 좁힙니다

먼저 오류 전체를 긴 로그로 보지 말고 핵심 줄만 따로 적습니다.

npm ERR! Missing script: "dev"

이 줄은 dev라는 npm script를 찾지 못했다는 신호입니다. Module not found, TypeScript 빨간 줄, 포트 충돌과는 출발점이 다릅니다. 그래서 바로 node_modules를 지우거나 파일을 대량 수정하면 원래 문제보다 더 큰 변경이 생길 수 있습니다.

처음 할 일은 프로젝트 루트에서 package.json을 여는 것입니다. 터미널이 어느 폴더에 있는지도 같이 봅니다.

pwd
ls

Windows PowerShell이라면 아래처럼 확인해도 됩니다.

Get-Location
Get-ChildItem

현재 폴더에 package.json이 없다면, 명령을 틀린 폴더에서 실행했을 가능성이 있습니다. 이 경우 AI에게 앱 수정을 맡기기 전에 프로젝트 폴더를 다시 찾는 편이 먼저입니다.

package.json의 scripts에서 실제 명령 이름을 찾습니다

package.json을 열면 보통 아래와 같은 영역이 있습니다.

{
  "scripts": {
    "start": "next start",
    "build": "next build"
  }
}

이 예시에는 dev가 없습니다. 이 상태에서 npm run dev를 계속 치면 같은 오류가 반복됩니다. npm 문서의 scripts 설명처럼 scripts에는 프로젝트가 실행할 수 있는 임의의 명령 이름이 들어갑니다. 즉, 여기 적힌 이름이 메뉴판입니다.

현재 프로젝트가 가진 명령 목록만 보고 싶다면 다음 명령도 쓸 수 있습니다.

npm run

npm scripts 문서는 scripts에 프로젝트 명령을 정의하고 npm run-script <stage> 또는 npm run <stage>로 실행할 수 있다고 설명합니다. 또 run-script 문서는 실행할 command를 주지 않으면 사용 가능한 scripts를 출력한다고 안내합니다. 그래서 초보자에게는 이 명령이 안전한 확인용입니다. 있는 명령을 먼저 확인하고, 없는 명령은 만들지 말지 판단합니다.

여기서 분기점은 세 가지입니다.

이 판단은 AI가 npm 오류를 고치자며 package-lock을 지우라 할 때 보는 3분 기준과도 연결됩니다. lockfile을 지울지 말지는 의존성 문제가 있을 때의 판단이고, Missing script는 먼저 명령 이름 문제입니다.

Tap to zoom

Next.js 프로젝트라면 next dev가 scripts에 연결돼야 합니다

Next.js CLI 문서는 next CLI가 개발 서버 실행, 빌드, 시작 같은 명령을 제공한다고 설명합니다. Next.js 프로젝트에서 로컬 개발 서버를 열려면 보통 next dev를 scripts에 연결합니다.

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

이렇게 되어 있으면 npm run dev는 next dev를 실행하는 짧은 입구가 됩니다. 반대로 scripts에 dev가 없다면 npm은 next dev를 대신 추측해서 실행하지 않습니다. npm run dev의 dev는 npm이 약속한 고정 명령이 아니라, 현재 프로젝트가 scripts에 적어 둔 이름입니다.

이미 dev가 있는데도 서버가 열리지 않는다면 그때는 다른 문제로 넘어갑니다. 예를 들어 서버가 3000번 포트에서 멈춘다면 Next.js dev 서버가 3000번에서 멈출 때, 포트 충돌을 3분 안에 푸는 순서를 같이 보면 됩니다. 지금 글의 범위는 그 전 단계, dev라는 입구가 있는지 확인하는 일입니다.

Next.js가 아닌 Vite, Astro, Express 프로젝트도 있습니다. 그래서 무조건 next dev를 추가하면 안 됩니다. dependencies나 기존 scripts를 보고 프로젝트 종류를 먼저 확인합니다.

{
  "dependencies": {
    "next": "15.3.0"
  }
}

Node.js의 npm 소개 문서는 package.json이 프로젝트의 의존성 정보를 담는다고 설명합니다. 그래서 next가 보이면 Next.js일 가능성이 큽니다. vite가 보이면 "dev": "vite"일 수 있습니다. 프로젝트마다 다르므로 AI에게도 "Next.js로 고쳐 줘"가 아니라 현재 dependencies와 scripts를 같이 보여 주는 편이 안전합니다.

AI에게는 앱 전체가 아니라 scripts 수정만 요청합니다

초보자가 가장 많이 손해 보는 지점은 이 오류를 "앱이 안 돌아간다"로 크게 설명하는 순간입니다. 그러면 AI는 파일 여러 개를 고치거나 의존성을 다시 설치하자고 할 수 있습니다. 이럴 때는 요청 범위를 작게 고정합니다.

Tap to zoom

아래처럼 묻습니다.

npm run dev를 실행했더니 Missing script: "dev"가 나왔습니다.

현재 package.json scripts는 아래와 같습니다.

{
  "scripts": {
    "build": "next build",
    "start": "next start"
  }
}

요청:
- 앱 전체 파일을 수정하지 마세요.
- 이 프로젝트가 Next.js인지 dependencies 기준으로 확인해 주세요.
- 로컬 개발 서버를 열려면 dev script를 추가해야 하는지, 아니면 기존 명령을 써야 하는지 판단해 주세요.
- 수정이 필요하다면 package.json의 scripts 변경만 제안해 주세요.

이 프롬프트의 핵심은 수정 범위를 package.json scripts로 묶는 것입니다. AI가 파일을 너무 많이 고칠 때, 초보가 3분 만에 막는 5줄 프롬프트에서처럼 먼저 범위를 좁혀야 나중에 되돌릴 변경도 줄어듭니다.

수정이 필요해서 dev를 추가했다면 바로 다음 검증은 하나입니다.

npm run dev

이제 오류가 Missing script에서 다른 메시지로 바뀌었다면, 한 단계는 해결된 것입니다. 다른 오류가 이어질 수는 있지만 원인이 좁아졌습니다. 그때는 새 오류 한 줄과 바뀐 scripts만 다시 확인하면 됩니다.

재설치 전에 scripts, 폴더, 목적을 순서대로 봅니다

Missing script: "dev"는 초보자를 불안하게 만들지만, 처음부터 큰 수리를 요구하는 오류는 아닙니다. 순서는 단순합니다. 현재 폴더가 프로젝트 루트인지 보고, package.json의 scripts를 열고, 실제로 존재하는 명령을 확인합니다. 그다음에야 dev를 추가할지 다른 명령을 실행할지 판단합니다.

오늘의 기준은 하나입니다. npm이 없다고 말한 것은 앱 전체가 아니라 dev라는 script 이름입니다. 이 차이를 먼저 나누면 AI에게 줄 질문도 짧아지고, 불필요한 재설치나 대량 수정도 줄어듭니다.

참고 출처

• npm Docs - npm-run-script
• npm Docs - scripts
• Next.js Docs - CLI
• Node.js Learn - An introduction to the npm package manager