Alpine Docker容器中FastAPI的VSCode调试报错：找不到uvicorn模块

核心原因 #

Alpine镜像默认的Python环境是精简版，pip安装的包可能不在VSCode调试器默认查找的sys.path中；加上调试时Python解释器路径与容器内运行路径不匹配，导致已安装的uvicorn无法被识别。

分步解决方案 #

1. 先验证容器内Python环境一致性 #

进入容器执行以下命令，确认路径匹配：

# 查看系统Python路径
which python3
# 查看pip路径
which pip3
# 查看uvicorn安装位置
pip3 show uvicorn | grep Location
# 查看Python默认搜索路径
python3 -c "import sys; print('\n'.join(sys.path))"

如果uvicorn的Location不在Python的sys.path输出列表里，说明包安装到了非默认路径，需要调整PYTHONPATH。

2. 修正Dockerfile配置 #

在Dockerfile中明确设置环境变量，确保依赖包能被系统Python识别：

FROM python:3.12-alpine

WORKDIR /app

# Alpine安装编译依赖（部分Python包需要，安装后可清理）
RUN apk add --no-cache gcc musl-dev linux-headers

COPY requirements.txt .
# 若用--user安装，需后续将路径加入PYTHONPATH；不加则默认安装到系统路径
RUN pip3 install --no-cache-dir -r requirements.txt

# 手动指定PYTHONPATH，包含包安装路径和项目根目录
ENV PYTHONPATH="/usr/local/lib/python3.12/site-packages:/app"

COPY . .

# 正常启动命令（调试时会被VSCode覆盖）
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

3. 调整VSCode launch.json配置 #

确保调试配置对应容器内的Python路径、路径映射和环境变量：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Docker: FastAPI调试",
            "type": "docker",
            "request": "launch",
            "preLaunchTask": "docker-run: debug",
            "python": {
                "pathMappings": [
                    {
                        "localRoot": "${workspaceFolder}",
                        "remoteRoot": "/app"
                    }
                ],
                "pythonPath": "/usr/local/bin/python3" // 与容器内which python3结果一致
            },
            "env": {
                "PYTHONPATH": "/usr/local/lib/python3.12/site-packages:/app" // 与Dockerfile对应
            }
        }
    ]
}

如果用attach模式，需先让容器暴露debug端口，同时调整launch.json：

{
    "name": "Docker: Attach到Python",
    "type": "python",
    "request": "attach",
    "connect": {
        "host": "localhost",
        "port": 5678
    },
    "pathMappings": [
        {
            "localRoot": "${workspaceFolder}",
            "remoteRoot": "/app"
        }
    ],
    "env": {
        "PYTHONPATH": "/usr/local/lib/python3.12/site-packages:/app"
    }
}

对应Dockerfile的调试启动命令：

CMD ["python3", "-m", "debugpy", "--listen", "0.0.0.0:5678", "--wait-for-client", "-m", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

4. 确认requirements.txt依赖完整 #

确保包含调试和运行必需的包：

fastapi>=0.104.1
uvicorn>=0.30.6
debugpy>=1.8.0
# 其他项目依赖...

5. 验证VSCode环境设置 #

• 确保Docker插件和Python插件为最新版本
• 打开命令面板（Ctrl+Shift+P），执行Python: Select Interpreter，选择对应Docker容器内的Python解释器

关键注意事项 #

• Alpine镜像中，pip install不加--user时，包默认安装到/usr/local/lib/pythonX.X/site-packages，该路径在Python默认搜索路径内；加--user则需手动将/root/.local/lib/pythonX.X/site-packages加入PYTHONPATH
• VSCode的路径映射必须准确，本地代码根目录要和容器内的WORKDIR完全对应
• 调试时VSCode会覆盖Dockerfile的CMD命令，需确保launch.json中的启动命令使用容器内正确的Python解释器路径

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