Sửa lỗi "listen EADDRINUSE: address already in use :::3000" trong VS Code Debug

TL;DR

Một tiến trình khác đang lắng nghe trên cổng 3000. Hãy tắt nó, sau đó khởi động lại phiên debug.

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

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

Thủ phạm thường là một phiên debug trước đó không thoát sạch — hãy đọc tiếp để hiểu rõ hơn.

Chuyện gì đang xảy ra

Mỗi lần bạn nhấn F5, VS Code khởi động một tiến trình Node.js (hoặc dev server) và gắn nó vào một cổng — ở đây là cổng 3000. Điều đó là bình thường. Vấn đề bắt đầu khi một phiên trước đó bị crash, bị tắt cưỡng bức, hoặc VS Code mất dấu nó.

Tiến trình cũ đó tiếp tục chạy ngầm, âm thầm chiếm giữ cổng. Phiên debug tiếp theo cố gắng sử dụng cùng cổng đó và thất bại ngay lập tức:

listen EADDRINUSE: address already in use :::3000

Tiền tố ::: có nghĩa là tiến trình đã gắn vào tất cả các giao diện IPv6 — trên hầu hết các hệ thống, điều này bao gồm cả IPv4. Vì vậy, việc chuyển đổi giữa localhost và 127.0.0.1 sẽ không giải quyết được. Bạn cần tắt tiến trình đó hoàn toàn.

Cách sửa 1: Tắt tiến trình đang chiếm cổng

macOS / Linux

# Tìm và tắt trong một lệnh
lsof -ti :3000 | xargs kill -9

# Hoặc từng bước:
lsof -i :3000
# Ghi lại PID trong kết quả, sau đó:
kill -9 <PID>

Windows (Command Prompt)

netstat -ano | findstr :3000
# Ghi lại PID ở cột cuối, sau đó:
taskkill /PID <PID> /F

Windows (PowerShell)

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

Sau khi tắt tiến trình, nhấn F5 lại. Lỗi sẽ biến mất.

Cách sửa 2: Dừng các phiên debug VS Code bị bỏ sót

Đôi khi tiến trình ma thuộc về một phiên debug VS Code trước đó. Bạn có thể tắt nó mà không cần rời khỏi trình soạn thảo:

Mở panel Run and Debug (Ctrl+Shift+D / Cmd+Shift+D)
Nhấn nút Stop hình vuông đỏ nếu có phiên nào đang hiển thị là đang hoạt động
Chuyển sang panel Terminal và nhấn Ctrl+C với các tiến trình vẫn đang chạy ở đó

Đây là điều nhiều người hay bị nhầm: các terminal tích hợp của VS Code giữ tiến trình sống ngay cả sau khi phiên debug có vẻ đã kết thúc trên giao diện. Hãy kiểm tra mọi tab terminal — bạn có thể có ba hoặc bốn tab đang mở từ các lần chạy trước.

Cách sửa 3: Đổi cổng debug

Cổng 3000 đang bị chiếm dụng hợp lệ? Có thể một dự án khác đang chạy ở đó, hoặc một dịch vụ hệ thống đã chiếm nó lúc khởi động. Thay vì tắt nó, hãy chuyển ứng dụng của bạn sang một cổng khác.

Trong file .env của bạn:

PORT=3001

Hoặc truyền trực tiếp khi khởi động:

PORT=3001 node server.js

Với các dự án Vite, cập nhật vite.config.ts:

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

Với Create React App, đặt PORT=3001 trong file .env — CRA sẽ tự động nhận giá trị này.

Cách sửa 4: Cấu hình VS Code tự động tắt khi khởi động lại

Thêm "restart": true vào file .vscode/launch.json. Điều này yêu cầu VS Code tự động khởi động lại phiên debug mỗi khi tiến trình thoát — nhờ đó các tiến trình cũ sẽ được dọn dẹp giữa các lần chạy:

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

Với các server cần bước tắt rõ ràng trước khi khởi động lại, hãy thêm preLaunchTask để chạy lệnh tắt của bạn. Một số debug adapter cũng hỗ trợ "killOnServerStop" — hãy kiểm tra tài liệu của adapter bạn đang dùng.

Cách sửa 5: Dùng gói kill-port

Nếu bạn gặp EADDRINUSE mỗi ngày, hãy ngừng xử lý thủ công. Thêm kill-port làm dev dependency:

npm install --save-dev kill-port

Sau đó kết nối nó vào package.json như một hook predev:

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

Mỗi lần chạy npm run dev giờ sẽ giải phóng cổng trước khi server khởi động. Không cần thêm lệnh nào khác.

Xác minh đã sửa xong

Trước khi nhấn F5, hãy xác nhận cổng thực sự đã trống:

# macOS / Linux
lsof -i :3000
# Không có kết quả là được

# Windows
netstat -ano | findstr :3000
# Không có kết quả là được

Không có kết quả nghĩa là cổng đã trống. Phiên debug tiếp theo của bạn sẽ khởi động bình thường.

Tại sao lỗi này cứ xảy ra

Bốn tình huống thường gây ra lỗi này lặp đi lặp lại:

Nhấn Restart trong VS Code trước khi tiến trình trước đó thoát hoàn toàn
VS Code bị crash hoặc bị tắt cưỡng bức giữa phiên
Chạy npm run dev trong một tab terminal đồng thời khởi động debugger bằng F5
Các container Docker hoặc dịch vụ khác được ánh xạ vào cùng cổng host

Thói quen tốt nhất về lâu dài: liếc nhìn panel Terminal trước mỗi lần nhấn F5. Tắt bất cứ thứ gì vẫn đang chạy ở đó. Chỉ mất hai giây và giúp tránh được 90% các lỗi này.

Để có giải pháp hoàn toàn tự động, script predev từ Cách sửa 5 xử lý mọi thứ mà không cần can thiệp thủ công.