Sửa lỗi "Extension is not compatible with the current version of VS Code"

Chuyện Gì Đã Xảy Ra

Bạn thử cài đặt hoặc bật một extension VS Code và nhận được thông báo này:

Extension '...' is not compatible with the current version of VS Code. Please update VS Code to use this extension.

Extension bị vô hiệu hóa hoặc từ chối cài đặt. Thường thì nguyên nhân rơi vào một trong ba trường hợp sau:

• VS Code của bạn đã cũ và extension cần phiên bản engine mới hơn.
• VS Code của bạn mới nhưng bạn lại cài một phiên bản extension cũ được xây dựng cho engine cũ hơn.
• Bạn đang dùng VS Code Insiders (bản pre-release) và extension chưa kịp hỗ trợ.

Tại Sao Lỗi Này Xảy Ra

Mỗi extension khai báo phiên bản engine tối thiểu trong file package.json của nó:

"engines": {
  "vscode": "^1.85.0"
}

VS Code kiểm tra điều này lúc cài đặt. Nếu phiên bản của bạn cũ hơn yêu cầu của extension, quá trình cài đặt sẽ bị chặn.

Sideload một file .vsix cũ là trường hợp ngược lại. Chẳng hạn bạn tải về một extension được xây dựng cho VS Code 1.60 — nó có thể gọi các API đã bị xóa từ phiên bản 1.85, dẫn đến cùng lỗi đó nhưng theo chiều ngược.

Cách Khắc Phục Nhanh: Cập Nhật VS Code

Cách này giải quyết khoảng 90% trường hợp. Thực hiện cập nhật ngay từ bên trong VS Code:

Windows / macOS

• Mở Command Palette: Ctrl+Shift+P (Windows) hoặc Cmd+Shift+P (macOS).
• Gõ Update: Check for Updates rồi nhấn Enter.
• VS Code tải bản cập nhật ngầm. Khi nút ở góc dưới bên trái hiển thị Restart to Update, hãy nhấn vào đó.

Linux (qua terminal)

# Snap
sudo snap refresh code

# APT (official Microsoft repo)
sudo apt update && sudo apt install --only-upgrade code

# RPM/DNF
sudo dnf upgrade code

Kiểm tra cập nhật có thành công không

code --version

Dòng đầu tiên là số phiên bản — ví dụ như 1.91.0. Đối chiếu với trang extension trên Marketplace. Trường VS Code Engine hiển thị phiên bản tối thiểu cần có.

Nếu Không Thể Cập Nhật VS Code

Máy tính công ty bị khóa cứng hoặc môi trường CI thường chặn toàn bộ việc cập nhật. Cách xử lý: cài một phiên bản extension cũ hơn tương thích với VS Code bạn đang dùng.

Phương án A — Cài phiên bản cụ thể từ giao diện Marketplace

• Mở panel Extensions (Ctrl+Shift+X).
• Tìm extension và nhấn vào tên để mở trang chi tiết.
• Nhấn mũi tên nhỏ cạnh nút Install → Install Another Version…
• Chọn phiên bản mới nhất được phát hành trước thời điểm phiên bản VS Code của bạn không còn tương thích.

Phương án B — Tải về và sideload file .vsix

• Vào trang extension trên marketplace.visualstudio.com.
• Nhấn Version History và tải về file .vsix tương thích.
• Cài đặt từ CLI:

code --install-extension path/to/extension-1.2.3.vsix

Hoặc từ panel Extensions: nhấn menu … → Install from VSIX…

Trường Hợp Đặc Biệt: VS Code Insiders

Bản Insiders mang số phiên bản nội bộ cao hơn bản stable hiện tại. Một số extension chưa khai báo tương thích với nó. Các lựa chọn của bạn:

• Chuyển sang kênh VS Code stable cho dự án đó.
• Chờ tác giả extension đẩy bản cập nhật — các thay đổi gây lỗi trên Insiders thường được vá trong vòng một đến hai tuần.
• Bật extension bản pre-release: trên trang chi tiết extension, gạt sang Switch to Pre-Release Version.

Giải Pháp Lâu Dài: Bật Tự Động Cập Nhật VS Code

Thay đổi cài đặt một lần để không gặp lại lỗi này nữa:

• Mở Settings: Ctrl+, (hoặc Cmd+, trên macOS).
• Tìm kiếm update mode.
• Đặt Update: Mode thành default — VS Code sẽ tải bản cập nhật âm thầm ở nền, sau đó nhắc bạn khởi động lại.

Hoặc thêm trực tiếp vào settings.json:

{
  "update.mode": "default"
}

Các giá trị hợp lệ: none, manual, start, default. Dùng default trừ khi bạn có lý do cụ thể để cố định phiên bản.

Xác Nhận Đã Khắc Phục

Sau khi cập nhật VS Code hoặc cài phiên bản extension tương thích:

• Mở panel Extensions (Ctrl+Shift+X).
• Extension sẽ hiển thị trạng thái Enabled mà không có biểu tượng cảnh báo.
• Kiểm tra panel Output (Ctrl+Shift+U, chọn Extension Host) để xem có lỗi còn sót lại không.
• Chạy thử tính năng chính của extension — nếu hoạt động được là xong.

Vẫn còn báo không tương thích? Mở Developer Tools qua Help → Toggle Developer Tools. Tab Console sẽ chỉ rõ đúng tên API call bị lỗi — hữu ích hơn nhiều so với thông báo lỗi bề mặt.

Tóm Tắt

• Đa số trường hợp: cập nhật VS Code (dùng code --version để xem phiên bản hiện tại).
• Không thể cập nhật: cài phiên bản extension cũ hơn qua Install Another Version… hoặc file .vsix tải về.
• Đang dùng Insiders: thử kênh extension pre-release hoặc chuyển sang bản stable.
• Lâu dài: đặt update.mode thành default trong settings.