npm run で Missing script エラーが出てスクリプトを実行できない

要約

npm ERR! Missing script は package.json の scripts にキーが無い、または 見ている package.json が違う のどちらか。npm run を引数なしで実行すれば現在のディレクトリの全 script が表示されるので、まずそこで切り分ける。

よくある原因

1. typo / 別名: start を serve と書くなど、ドキュメントと実装で script 名が違う
2. 間違ったディレクトリ: monorepo で apps/web 配下にいるのに root の script を期待している
3. workspace の指定漏れ: workspaces 構成で -w を付けずに root から子の script を呼んでいる
4. package.json 破損: 末尾カンマや quote の不整合で JSON 全体が読めず、scripts も空扱い
5. script-shell 設定: 過去に npm config set script-shell で無効な shell を指定していると、全 script が失敗する

解決策

1. 一覧表示で確認する

npm run

引数なしで実行すると、現在のディレクトリの package.json に定義された script 一覧が表示される。
ここに無ければ存在しない（npm-run-script 公式 参照）。

2. package.json を直接確認する

jq .scripts package.json

jq が無ければ cat package.json でも可。
typo の確認はここで終わらせる。

3. ディレクトリ位置を確認する

pwd
ls package.json

monorepo では root と app それぞれに package.json がある。
app 側を動かしたいなら cd apps/web してから npm run dev。

4. workspace の場合

# root から子 workspace の script を指定
npm run build -w @scope/app
 
# 全 workspace で実行（script が無い workspace は skip）
npm run build --workspaces --if-present

scripts の挙動全般は公式の Using npm/scriptsを参照。

5. shell 設定をリセット

npm config get script-shell
npm config delete script-shell   # 既定（OS 標準シェル）に戻す

ユーザ単位の ~/.npmrc の設定が壊れていると、全 script が command not found を返す。