WSL调试FastAPI遇ModuleNotFoundError问题求解

问题背景 #

在WSL中调试FastAPI项目时，首次出现报错：

ERROR: Error loading ASGI app. Could not import module "knowledge"

修改launch.json的args为src.knowledge:create_app后，又出现内部导入错误：

ModuleNotFoundError: No module named 'knowledge'

但通过poetry shell进入虚拟环境后执行poetry run start能正常启动项目。

报错原因 #

VS Code调试时的Python模块搜索路径（sys.path）与Poetry运行环境不一致：

• Poetry会自动将项目的源码目录或根目录加入sys.path，确保knowledge模块能被识别；
• 调试场景下默认未配置该路径，导致内部绝对导入from knowledge.schema...无法定位模块。

解决方案 #

方案1：配置PYTHONPATH环境变量（推荐） #

修改launch.json，添加env字段将项目根目录加入PYTHONPATH，同时调整ASGI app路径与Poetry启动时一致：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: FastAPI",
            "type": "python",
            "request": "launch",
            "module": "uvicorn",
            "args": [
                "knowledge:create_app",
                "--port",
                "8000",
                "--reload"
            ],
            "jinja": true,
            "justMyCode": true,
            "env": {
                "PYTHONPATH": "${workspaceFolder}"
            }
        }
    ]
}

方案2：改用相对导入 #

将项目内部的绝对导入改为相对导入，例如在src/knowledge/__init__.py中：

# 原绝对导入
from knowledge.schema.app_schema import APIResponse
# 修改为相对导入
from .schema.app_schema import APIResponse

该方法适合小型项目，大型项目修改成本较高。

方案3：通过Poetry命令启动调试 #

直接调用Poetry命令启动Uvicorn，确保调试环境与运行环境完全一致：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: FastAPI via Poetry",
            "type": "python",
            "request": "launch",
            "command": "poetry",
            "args": [
                "run",
                "uvicorn",
                "knowledge:create_app",
                "--port",
                "8000",
                "--reload"
            ],
            "jinja": true,
            "justMyCode": true
        }
    ]
}

内容的提问来源于stack exchange，提问作者Martin