Sửa lỗi Pylance "Import could not be resolved from source file" trong VS Code

Tìm hiểu lỗi Import của Pylance

Lỗi Import "module_name" could not be resolved from source file là một vấn đề thường gặp đối với các lập trình viên Python sử dụng VS Code với language server Pylance. Nó cho biết rằng mặc dù mã nguồn của bạn có thể thực sự chạy đúng trong terminal, nhưng Pylance (trình kiểm tra kiểu tĩnh) không thể tìm thấy mã nguồn của module được import để cung cấp các tính năng IntelliSense, kiểm tra kiểu và điều hướng.

# Ví dụ về lỗi hiển thị trong trình soạn thảo
import requests  # Error: Import "requests" could not be resolved from source file
from my_local_module import helper # Error: Import "my_local_module" could not be resolved from source file

Điều này xảy ra vì Pylance tìm kiếm các module trong một tập hợp các đường dẫn cụ thể, và nếu môi trường của bạn không được cấu hình đúng trong VS Code, nó sẽ không thể ánh xạ lệnh import tới một tệp vật lý trên đĩa cứng.

Bước 1: Xác minh Python Interpreter

Nguyên nhân phổ biến nhất là VS Code đang sử dụng một Python interpreter khác với trình thông dịch nơi các gói (package) của bạn được cài đặt. Ví dụ, bạn có thể đã cài đặt pandas trong một môi trường ảo (venv), nhưng VS Code lại đang sử dụng Python hệ thống toàn cục.

• Nhấn Ctrl + Shift + P (Windows/Linux) hoặc Cmd + Shift + P (macOS) để mở Command Palette.
• Nhập Python: Select Interpreter và chọn nó.
• Chọn interpreter tương ứng với môi trường ảo của bạn. Nó thường có dạng ./venv/bin/python hoặc ('venv': venv).

Đợi vài giây để Pylance lập lại chỉ mục (re-index). Nếu dấu gạch sóng màu đỏ biến mất, nguyên nhân chính là do sự không khớp của interpreter.

Bước 2: Cấu hình Extra Paths cho các Module cục bộ

Nếu bạn đang làm việc với một cấu trúc dự án không chuẩn, chẳng hạn như đặt tất cả mã nguồn trong thư mục src/, Pylance có thể không biết để tìm kiếm bên trong thư mục đó.

Để khắc phục điều này, bạn cần thông báo cho Pylance về các thư mục bổ sung này thông qua tệp settings.json.

• Tạo hoặc mở tệp .vscode/settings.json trong thư mục gốc của dự án.
• Thêm cấu hình python.analysis.extraPaths:

{
    "python.analysis.extraPaths": [
        "./src",
        "./path/to/your/custom/modules"
    ]
}

Điều này yêu cầu Language Server Protocol (LSP) bao gồm các thư mục này khi tìm kiếm định nghĩa của module.

Bước 3: Kiểm tra Workspace Root

Pylance phân giải các đường dẫn tương đối so với thư mục hiện đang mở trong VS Code. Nếu bạn mở một thư mục "cha" chứa nhiều dự án con, Pylance có thể bị nhầm lẫn về các gốc (root) import.

Cách khắc phục: Luôn mở thư mục gốc của dự án cụ thể làm workspace trong VS Code. Nếu bạn có cấu trúc như /projects/my_python_app/, hãy mở trực tiếp thư mục my_python_app thay vì thư mục projects.

Bước 4: Sử dụng tệp .env cho PYTHONPATH

Đôi khi, mã nguồn của bạn dựa vào biến môi trường PYTHONPATH để tìm các module khi thực thi. Pylance cũng có thể tuân theo các cài đặt này nếu bạn sử dụng tệp .env.

• Tạo một tệp tên là .env trong thư mục gốc của dự án.
• Thêm thư mục nguồn của bạn vào đường dẫn:

PYTHONPATH=src

• Trong tệp .vscode/settings.json của bạn, hãy đảm bảo tệp env đã được tải:

{
    "python.envFile": "${workspaceFolder}/.env"
}

Bước 5: Làm mới Pylance Language Server

Đôi khi, chỉ mục nội bộ của Pylance trở nên cũ hoặc bị lỗi, đặc biệt là sau một phiên cài đặt pip install lớn. Việc khởi động lại server có thể buộc hệ thống quét lại các site-package của bạn.

• Mở Command Palette (Ctrl + Shift + P).
• Nhập Python: Restart Language Server.

Xác minh: Cách kiểm tra xem lỗi đã được khắc phục chưa

Để đảm bảo vấn đề được giải quyết đúng cách, hãy thực hiện các bước kiểm tra sau:

• Kiểm tra trực quan: Dấu gạch sóng màu đỏ dưới câu lệnh import sẽ biến mất.
• Go to Definition (Đi tới định nghĩa): Di chuột qua tên module được import, giữ phím Ctrl (hoặc Cmd) và nhấp chuột. Nếu VS Code mở tệp nguồn của module đó, việc phân giải đường dẫn đang hoạt động chính xác.
• IntelliSense: Nhập tên module kèm theo dấu chấm (ví dụ: module_name.). Nếu danh sách các hàm và lớp xuất hiện, Pylance đã lập chỉ mục module thành công.

Mẹo tóm tắt

• Luôn sử dụng môi trường ảo (python -m venv venv) để giữ cho các phụ thuộc được cô lập.
• Nếu bạn vừa cài đặt một gói, hãy để Pylance một lát để lập chỉ mục trước khi cho rằng có lỗi.
• Kiểm tra tệp pyrightconfig.json hoặc pyproject.toml nếu bạn đang sử dụng chúng để cấu hình kiểm tra kiểu, vì chúng có thể ghi đè các cài đặt của VS Code.