Cách khắc phục lỗi 'Unable to resolve workspace folder' trong VS Code

Vấn đề

Gần đây tôi đã gặp phải một vấn đề gây khó chịu khi VS Code đột ngột từ chối tải các thư mục dự án của mình. Thay vì các tệp xuất hiện trong thanh bên, tôi nhận được một thông báo cho biết: Unable to resolve workspace folder. Điều này thường xảy ra khi bạn đang sử dụng Multi-Root Workspace hoặc tệp .code-workspace, và VS Code không còn tìm thấy một trong các thư mục được định nghĩa trong cấu hình đó.

Lỗi này đặc biệt phổ biến sau khi bạn di chuyển các thư mục trên ổ cứng, đổi tên thư mục cha, hoặc nếu bạn đang làm việc với các tệp dự án được lưu trữ trên ổ cứng ngoài hoặc ổ đĩa mạng chưa được kết nối.

Tại sao điều này xảy ra

Khi bạn lưu một workspace trong VS Code, nó sẽ tạo ra một tệp JSON với phần mở rộng .code-workspace. Tệp này chứa các đường dẫn tuyệt đối hoặc tương đối đến các thư mục dự án của bạn. Nếu bất kỳ đường dẫn nào trong số đó trở nên không hợp lệ, VS Code sẽ báo lỗi Unable to resolve workspace folder vì nó không muốn hiển thị cho bạn một môi trường trống hoặc bị lỗi.

Các nguyên nhân phổ biến:

Đổi tên thư mục dự án bên ngoài VS Code.
Di chuyển tệp .code-workspace sang một cấp thư mục khác.
Ổ đĩa mạng chưa được mount hoặc bộ nhớ USB bị ngắt kết nối.
Xóa một thư mục vốn là một phần của thiết lập multi-root.

Các bước khắc phục

1. Chỉnh sửa tệp .code-workspace theo cách thủ công

Cách nhanh nhất để khắc phục việc này là đi thẳng vào nguồn dữ liệu. Nếu bạn vẫn có thể mở chính tệp workspace đó, hãy thực hiện ngay. Nếu không, hãy tìm nó trong trình quản lý tệp và mở bằng một trình chỉnh sửa văn bản (ngay cả Notepad hoặc Vim cũng được).

{
    "folders": [
        {
            "path": "frontend"
        },
        {
            "path": "../backend-api"
        },
        {
            "name": "Docs",
            "path": "/Users/dev/documents/project-notes"
        }
    ],
    "settings": {}
}

Hãy nhìn vào các giá trị path. Kiểm tra xem các thư mục đó có thực sự tồn tại ở các vị trí đó không. Nếu bạn đã di chuyển thư mục backend, hãy cập nhật đường dẫn tại đây. Nếu bạn đang dùng Windows, hãy đảm bảo ký tự ổ đĩa (ví dụ: D:) là chính xác.

2. Sử dụng đường dẫn tương đối thay vì đường dẫn tuyệt đối

Tôi nhận thấy rằng việc sử dụng đường dẫn tuyệt đối (như C:\Users\Admin\Project) rất dễ gây lỗi nếu bạn chia sẻ tệp workspace của mình với đồng nghiệp hoặc di chuyển giữa các máy tính khác nhau. Hãy chuyển sang đường dẫn tương đối bất cứ khi nào có thể.

Nếu tệp .code-workspace của bạn nằm ở thư mục gốc của dự án, các đường dẫn của bạn nên trông như thế này:

"folders": [
    {
        "path": "."
    },
    {
        "path": "packages/api"
    }
]

3. Xóa và thêm lại thư mục

Nếu việc chỉnh sửa JSON tạo cảm giác quá thủ công, bạn có thể khắc phục thông qua giao diện người dùng của VS Code (nếu cửa sổ vẫn đang mở):

Nhấp chuột phải vào thư mục bị lỗi trong ngăn Explorer (nó thường có một dấu 'x' nhỏ hoặc biểu tượng cảnh báo).
Chọn Remove Folder from Workspace.
Đi tới File > Add Folder to Workspace... và tìm đến vị trí mới của thư mục đó.
Lưu lại workspace một lần nữa (File > Save Workspace As...).

4. Kiểm tra các kết nối mạng và ổ cứng ngoài

Trên Linux và macOS, tôi thường thấy lỗi này khi một Docker volume hoặc NFS mount không hoạt động. Nếu đường dẫn workspace của bạn trỏ đến /mnt/data/projects, hãy chạy một kiểm tra nhanh trong terminal:

ls /mnt/data/projects

Nếu bạn nhận được lỗi "No such file or directory", bạn cần phải mount lại ổ đĩa trước khi VS Code có thể giải quyết được thư mục workspace.

5. Xóa bộ nhớ lưu trữ Workspace của VS Code

Đôi khi VS Code bị kẹt ở một phiên bản lưu đệm của một workspace không còn tồn tại. Nếu bạn đã xóa tệp .code-workspace nhưng VS Code vẫn tiếp tục cố gắng mở nó khi khởi động, bạn có thể cần phải xóa trạng thái nội bộ.

Điều hướng đến thư mục lưu trữ toàn cục của VS Code và tìm thư mục workspaceStorage. Bạn có thể thử xóa các thư mục bên trong (cảnh báo: việc này sẽ thiết lập lại trạng thái giao diện người dùng như các tab đang mở và kích thước cửa sổ cho các dự án đó).

Windows: %APPDATA%\Code\User\workspaceStorage\
macOS: ~/Library/Application Support/Code/User/workspaceStorage/
Linux: ~/.config/Code/User/workspaceStorage/

Xác minh bản sửa lỗi

Sau khi bạn đã cập nhật các đường dẫn hoặc mount lại ổ đĩa, đây là cách để xác nhận mọi thứ đã trở lại bình thường:

Đóng tất cả các cửa sổ VS Code.
Mở terminal và gõ code path/to/your/project.code-workspace.
Kiểm tra thanh bên Explorer (Ctrl+Shift+E hoặc Cmd+Shift+E). Tất cả các thư mục bây giờ sẽ được mở rộng mà không có biểu tượng lỗi.
Thử chạy tính năng "Search in Files" (Ctrl+Shift+F). Nếu nó trả về kết quả từ tất cả các thư mục, việc giải quyết workspace đã hoạt động hoàn toàn.

Mẹo để ngăn chặn các sự cố về đường dẫn

Giữ ở cục bộ: Cố gắng giữ tất cả các thư mục trong một multi-root workspace dưới cùng một thư mục cha để bạn có thể sử dụng các đường dẫn tương đối đơn giản.
Git ignore: Nếu bạn sử dụng đường dẫn tuyệt đối vì thiết lập máy cụ thể của mình, hãy thêm các tệp *.code-workspace vào .gitignore để không làm hỏng môi trường làm việc của đồng nghiệp.
Sử dụng Symbolic Links: Nếu bạn bắt buộc phải có các thư mục ở những vị trí lạ, hãy tạo một symlink bên trong thư mục dự án chính trỏ đến vị trí bên ngoài. VS Code xử lý các symlink tốt hơn nhiều so với các định nghĩa workspace bị hỏng.