Cách sửa lỗi: ESLint 'Failed to load parser @typescript-eslint/parser' trong VS Code

Thông báo lỗi

Bạn mở một tệp TypeScript trong VS Code, mong đợi một không gian làm việc sạch sẽ, nhưng một thông báo màu đỏ hiện lên. Hoặc, bạn kiểm tra bảng điều khiển ESLint Output và thấy dòng chữ khó chịu này:

Failed to load parser '@typescript-eslint/parser' declared in '.eslintrc.js': Cannot find module '@typescript-eslint/parser'

Điều gì đang thực sự xảy ra?

Về cơ bản, ESLint đang báo rằng nó không thể tìm thấy hướng dẫn phân tích cú pháp cho TypeScript. Nó biết rằng nó cần sử dụng @typescript-eslint/parser, nhưng các tệp vật lý bị thiếu hoặc công cụ không nhìn thấy chúng. Điều này thường xảy ra vì một vài lý do cụ thể sau:

Package chưa từng được cài đặt hoặc vô tình bị xóa.
Bạn đang làm việc trong một monorepo, và VS Code đang tìm kiếm ở thư mục gốc thay vì sub-package.
Phiên bản parser và ESLint plugin của bạn đang xung đột với nhau.
Thư mục node_modules của bạn đã bị lỗi (corrupted).

Bước 1: Cài đặt các dependency còn thiếu

Bắt đầu với những điều cơ bản. Nếu bạn vừa clone một repo hoặc khởi tạo một dự án mới, có thể bạn đã bỏ lỡ parser. Hãy chạy lệnh này trong thư mục gốc của dự án để đảm bảo mọi thứ đã sẵn sàng:

# Dành cho người dùng npm
npm install --save-dev @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint

# Dành cho người dùng yarn
yarn add -D @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint

# Dành cho người dùng pnpm
pnpm add -D @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint

Luôn cài đặt parser và eslint-plugin cùng nhau. Chúng được thiết kế để đi thành cặp, và việc thiếu một trong hai thường sẽ làm hỏng cái còn lại.

Bước 2: Đồng bộ hóa các số phiên bản

Phiên bản không khớp là một "kẻ giết người thầm lặng". Nếu parser của bạn ở phiên bản 7.x.x nhưng plugin vẫn ở 6.x.x, ESLint có thể thất bại khi kết nối chúng. Hãy mở tệp package.json và kiểm tra phần devDependencies.

Đảm bảo các phiên bản chính (major versions) khớp nhau hoàn toàn, như thế này:

"devDependencies": {
  "@typescript-eslint/eslint-plugin": "^7.2.0",
  "@typescript-eslint/parser": "^7.2.0",
  "eslint": "^8.57.0"
}

Sau khi chỉnh sửa tệp, hãy chạy npm install hoặc yarn install để áp dụng các thay đổi. Sự nhất quán ở đây giúp ngăn ngừa 90% các lỗi tải parser.

Bước 3: Cấu hình VS Code cho Monorepo

Trong một thiết lập monorepo (như Nx, Turbo, hoặc Yarn Workspaces), VS Code thường tìm kiếm node_modules sai chỗ. Nó có thể tìm ở thư mục gốc trong khi parser thực tế lại nằm trong /apps/web/node_modules.

Để khắc phục điều này, hãy tạo hoặc chỉnh sửa tệp .vscode/settings.json tại thư mục gốc của workspace:

{
  "eslint.workingDirectories": [
    { "mode": "auto" }
  ]
}

Nếu "auto" không hoạt động, hãy thử chỉ định rõ ràng. Cho VS Code biết chính xác vị trí các dự án của bạn:

{
  "eslint.workingDirectories": [
    "./apps/frontend",
    "./apps/backend",
    "./packages/shared-ui"
  ]
}

Bước 4: Giải pháp triệt để (Cài đặt lại sạch sẽ)

Đôi khi, cây dependency trở nên lộn xộn. Nếu bạn đã kiểm tra phiên bản và đường dẫn nhưng lỗi vẫn không biến mất, đã đến lúc xóa bỏ thư mục node_modules. Điều này sẽ dọn sạch mọi tệp rác hoặc symlink bị hỏng.

# Xóa các thư mục và tệp lockfile
rm -rf node_modules
rm package-lock.json # hoặc yarn.lock / pnpm-lock.yaml

# Cài đặt mới
npm install

Bước 5: Buộc khởi động lại ESLint Server

VS Code vốn nổi tiếng với việc lưu bộ nhớ đệm (cache) các lỗi cũ. Bạn có thể đã sửa tệp trên ổ đĩa, nhưng extension ESLint vẫn đang nhìn vào một bản chụp "bị lỗi". Đừng khởi động lại toàn bộ máy tính; chỉ cần khởi động lại server.

Nhấn Ctrl + Shift + P (hoặc Cmd + Shift + P trên Mac).
Nhập "ESLint: Restart ESLint Server".
Nhấn Enter và đợi vài giây.

Xác minh

Lỗi đã thực sự được khắc phục chưa? Hãy mở một tệp .ts và kiểm tra thanh trạng thái bên dưới trong VS Code. Bạn sẽ thấy một biểu tượng "ESLint" nhỏ. Nếu nó có dấu kiểm hoặc không có biểu tượng nào, bạn đã thành công. Nếu thấy dấu 'x' màu đỏ, hãy nhấp vào đó để mở bảng Output và xem còn lỗi nào cần sửa.

Mẹo nhanh

Tránh cài đặt Global: Đừng bao giờ chạy npm install -g eslint. Các parser cài đặt global thường xung đột với phiên bản dự án cục bộ, dẫn đến chính lỗi mà bạn đang gặp phải.
Kiểm tra phiên bản Node: Nếu bạn đang dùng phiên bản Node quá cũ (như v14) trong khi cố gắng chạy ESLint 9, bạn sẽ gặp rào cản về khả năng tương thích. Hãy sử dụng nvm để duy trì phiên bản LTS hiện đại như v20.