VS Codeデバッグで「listen EADDRINUSE: address already in use :::3000」を修正する

TL;DR

別のプロセスがすでにポート3000をリッスンしています。そのプロセスを終了してから、デバッグセッションを再起動してください。

# macOS / Linux
lsof -ti :3000 | xargs kill -9

# Windows (PowerShell)
Get-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess | Stop-Process -Force

クリーンに終了しなかった前回のデバッグセッションが原因であることがほとんどです — 詳しくは以下をお読みください。

何が起きているのか

F5を押すたびに、VS CodeはNode.jsプロセス（またはdevサーバー）を起動し、ポートにバインドします — ここではポート3000です。これ自体は正常な動作です。問題は、前のセッションがクラッシュしたり、強制終了されたり、VS Codeがそのセッションを追跡できなくなった場合に発生します。

その古いプロセスはバックグラウンドで実行し続け、静かにポートを占有します。次のデバッグセッションが同じポートを使おうとすると、即座に失敗します：

listen EADDRINUSE: address already in use :::3000

::: というプレフィックスは、プロセスがすべてのIPv6インターフェースにバインドされていることを意味します — ほとんどのシステムではIPv4も含まれます。そのため、localhost と 127.0.0.1 を切り替えても解決しません。プロセスを直接終了させる必要があります。

解決策1：ポートを使用しているプロセスを終了する

macOS / Linux

# 1行で検索して終了
lsof -ti :3000 | xargs kill -9

# または段階的に：
lsof -i :3000
# 出力に表示されるPIDを確認してから：
kill -9 <PID>

Windows（コマンドプロンプト）

netstat -ano | findstr :3000
# 最後の列のPIDを確認してから：
taskkill /PID <PID> /F

Windows（PowerShell）

Get-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess | Stop-Process -Force

プロセスを終了したら、再度F5を押してください。エラーは解消されているはずです。

解決策2：孤立したVS Codeデバッグセッションを停止する

ゴーストプロセスが前回のVS Codeデバッグセッションのものである場合があります。エディターを離れることなく終了できます：

実行とデバッグパネルを開く（Ctrl+Shift+D / Cmd+Shift+D）
アクティブなセッションが表示されている場合は、赤い四角の停止ボタンをクリックする
ターミナルパネルに切り替えて、まだ実行中のプロセスをCtrl+Cで停止する

よくある落とし穴として：VS Codeの統合ターミナルは、UIでデバッグセッションが終了したように見えた後もプロセスを生かし続けます。すべてのターミナルタブを確認してください — 以前の実行から3〜4個開いたままになっている場合があります。

解決策3：デバッグポートを変更する

ポート3000が正当な理由で使用されている場合はどうでしょうか？別のプロジェクトが実行中だったり、システムサービスが起動時に占有したりしている場合があります。終了させる代わりに、アプリを別のポートに変更してください。

.env ファイルで：

PORT=3001

または起動時にインラインで渡す：

PORT=3001 node server.js

Viteプロジェクトの場合は、vite.config.ts を更新してください：

export default defineConfig({
  server: {
    port: 3001
  }
})

Create React Appの場合は、.env ファイルに PORT=3001 を設定してください — CRAは自動的に読み込みます。

解決策4：VS Codeが再起動時に自動終了するよう設定する

.vscode/launch.json に "restart": true を追加してください。これにより、プロセスが終了するたびにVS Codeがデバッグセッションを自動的に再起動するようになり、実行間で古いプロセスがクリーンアップされます：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "program": "${workspaceFolder}/index.js",
      "restart": true,
      "autoAttachChildProcesses": true
    }
  ]
}

再起動前に明示的な終了ステップが必要なサーバーの場合は、終了コマンドを実行する preLaunchTask を追加してください。一部のデバッグアダプターは "killOnServerStop" もサポートしています — お使いのアダプターのドキュメントを確認してください。

解決策5：kill-portパッケージを使用する

EADDRINUSEが頻繁に発生する場合は、手動での対処をやめましょう。kill-port を開発依存関係として追加してください：

npm install --save-dev kill-port

次に、package.json の predev フックとして組み込みます：

"scripts": {
  "predev": "kill-port 3000",
  "dev": "node server.js"
}

npm run dev を実行するたびに、サーバーが起動する前にポートがクリアされます。余分なコマンドは一切不要です。

修正を確認する

F5を押す前に、ポートが実際に空いていることを確認してください：

# macOS / Linux
lsof -i :3000
# 何も返されなければOK

# Windows
netstat -ano | findstr :3000
# 何も返されなければOK

出力がなければポートは空いています。次のデバッグセッションはクリーンに起動するはずです。

なぜ繰り返し発生するのか

この問題が繰り返し起きる状況は4つあります：

前のプロセスが完全に終了する前にVS Codeで再起動をクリックする
VS Codeがセッション中にクラッシュするか強制終了される
ターミナルタブで npm run dev を実行しながら、同時に F5でデバッガーを起動する
同じホストポートにマッピングされたDockerコンテナやその他のサービス

長期的に有効な習慣として：F5を押す前にターミナルパネルをさっと確認してください。まだ実行中のプロセスをすべて終了させましょう。2秒で完了し、このエラーの90%を防ぐことができます。

完全に自動化されたソリューションとしては、解決策5の predev スクリプトが手動操作なしで対処してくれます。