侧边栏壁纸
博主头像
Euler的博客

  • 累计撰写 145 篇文章
  • 累计创建 19 个标签
  • 累计收到 0 条评论

目 录CONTENT

文章目录
开发工具

【工具】在Cursor/VS Code中配置Python调试环境的完整指南

EulerBlind
EulerBlind
2025-07-02 / 0 评论 / 0 点赞 / 2 阅读 / 0 字

Python作为一种灵活强大的编程语言，拥有良好的调试体验对开发效率至关重要。本文将详细介绍如何在Cursor编辑器中配置Python调试环境，包括不同类型应用的调试配置、环境变量设置以及各种控制台选项的区别。

一、前期准备

在开始配置之前，需要确保以下环境已就绪：

  1. 安装Python（建议3.8或更高版本）
  2. 安装Cursor编辑器
  3. 安装必要的Python包： 
    pip install debugpy pylint black mypy

二、项目结构示例

为了演示配置过程，我们以一个包含多个Python应用的项目为例：

my_workspace/
├── .vscode/                    # VS Code/Cursor配置文件夹
│   ├── launch.json             # 调试配置文件
│   └── settings.json           # Python设置文件
├── web_app/                    # Flask网站应用
│   ├── app.py
│   ├── config.py
│   └── requirements.txt
├── api_service/                # FastAPI服务
│   ├── main.py
│   ├── models.py
│   └── requirements.txt
└── data_processor/             # 数据处理脚本
    ├── processor.py
    └── utils.py

三、创建基础调试配置

首先，需要创建 .vscode目录并添加 launch.json文件：

mkdir -p .vscode
touch .vscode/launch.json

基础 launch.json配置

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python调试：当前文件",
            "type": "debugpy",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "justMyCode": false
        }
    ]
}

这是最基本的配置，允许调试当前打开的Python文件。

四、为不同应用类型配置调试

1. Flask应用调试配置

以下是 web_app的Flask应用调试配置：

{
    "name": "Flask应用",
    "type": "debugpy",
    "request": "launch",
    "module": "flask",
    "env": {
        "FLASK_APP": "web_app/app.py",
        "FLASK_ENV": "development",
        "FLASK_DEBUG": "1"
    },
    "args": [
        "run",
        "--no-debugger"
    ],
    "jinja": true,
    "console": "integratedTerminal"
}

2. FastAPI应用调试配置

以下是 api_service的FastAPI应用调试配置：

{
    "name": "FastAPI服务",
    "type": "debugpy",
    "request": "launch",
    "module": "uvicorn",
    "args": [
        "api_service.main:app",
        "--host", "0.0.0.0",
        "--port", "8000",
        "--reload"
    ],
    "console": "integratedTerminal",
    "python": "/path/to/your/python",
    "cwd": "${workspaceFolder}",
    "env": {
        "DATABASE_URL": "postgresql://user:password@localhost/dbname",
        "API_KEY": "your_api_key",
        "PYTHONUNBUFFERED": "1"
    },
    "justMyCode": false,
    "subProcess": true
}

3. 数据处理脚本调试配置

以下是 data_processor的调试配置：

{
    "name": "数据处理器",
    "type": "debugpy",
    "request": "launch",
    "program": "${workspaceFolder}/data_processor/processor.py",
    "args": [
        "--input", "data/input.csv",
        "--output", "data/output.csv"
    ],
    "console": "internalConsole",
    "env": {
        "PYTHONPATH": "${workspaceFolder}",
        "LOG_LEVEL": "DEBUG"
    },
    "redirectOutput": true
}

五、console选项详解

Cursor中的 console选项决定了程序运行时输出的显示位置。主要有三种选择：

1. integratedTerminal（集成终端）

"console": "integratedTerminal"

这是默认选项，程序在Cursor内置的终端窗口中运行。适合Web应用和需要交互式输入的程序。

2. internalConsole（调试控制台）

"console": "internalConsole",
"redirectOutput": true

程序输出显示在调试控制台面板中，更接近传统IDE的调试体验。建议添加 "redirectOutput": true以确保输出都重定向到调试控制台。

3. externalTerminal（外部终端）

"console": "externalTerminal"

程序在系统默认终端中运行，适合需要大量输出或需要系统权限的程序。

六、高级配置选项

1. Python解释器和环境

明确指定Python解释器路径：

"python": "/path/to/your/python"

2. 环境变量设置

"env": {
    "DATABASE_URL": "postgresql://user:password@localhost/dbname",
    "API_KEY": "your_api_key",
    "PYTHONUNBUFFERED": "1"
}

3. Python参数

传递给Python解释器的参数：

"pythonArgs": [
    "-X", "pycache_prefix=${env:HOME}/Library/Caches/Cursor/cpython-cache"
]

4. 多进程调试

支持调试由主进程启动的子进程：

"subProcess": true

5. 调试第三方库代码

允许进入第三方库的源代码进行调试：

"justMyCode": false

七、完整的配置文件示例

以下是一个包含多种调试配置的完整 launch.json文件：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "当前文件",
            "type": "debugpy",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal"
        },
        {
            "name": "Flask应用",
            "type": "debugpy",
            "request": "launch",
            "module": "flask",
            "env": {
                "FLASK_APP": "web_app/app.py",
                "FLASK_ENV": "development",
                "FLASK_DEBUG": "1"
            },
            "args": [
                "run",
                "--no-debugger"
            ],
            "jinja": true,
            "console": "integratedTerminal"
        },
        {
            "name": "FastAPI服务",
            "type": "debugpy",
            "request": "launch",
            "module": "uvicorn",
            "args": [
                "api_service.main:app",
                "--host", "0.0.0.0",
                "--port", "8000",
                "--reload"
            ],
            "console": "integratedTerminal",
            "env": {
                "DATABASE_URL": "postgresql://user:password@localhost/dbname",
                "API_KEY": "your_api_key",
                "PYTHONUNBUFFERED": "1"
            },
            "justMyCode": false,
            "subProcess": true
        },
        {
            "name": "数据处理器 (Debug Console)",
            "type": "debugpy",
            "request": "launch",
            "program": "${workspaceFolder}/data_processor/processor.py",
            "args": [
                "--input", "data/input.csv",
                "--output", "data/output.csv"
            ],
            "console": "internalConsole",
            "env": {
                "PYTHONPATH": "${workspaceFolder}",
                "LOG_LEVEL": "DEBUG"
            },
            "redirectOutput": true
        },
        {
            "name": "附加到进程",
            "type": "debugpy",
            "request": "attach",
            "connect": {
                "host": "localhost",
                "port": 5678
            }
        }
    ]
}

八、配置Python其他设置

除了调试配置外，还建议在 .vscode/settings.json中添加以下Python设置：

{
    "python.linting.enabled": true,
    "python.linting.pylintEnabled": true,
    "python.linting.lintOnSave": true,
    "python.formatting.provider": "black",
    "editor.formatOnSave": true,
    "python.formatting.blackArgs": [
        "--line-length",
        "88"
    ],
    "python.linting.mypyEnabled": true,
    "python.languageServer": "Pylance"
}

九、实际调试操作流程

  1. 设置断点：在代码中点击行号左侧设置断点
  2. 选择调试配置：在调试面板选择合适的配置
  3. 启动调试：点击绿色的运行按钮或按F5
  4. 调试控制：使用调试工具栏进行单步执行、步入、步出等操作
  5. 查看变量：在调试面板中检查变量值和调用堆栈

十、远程调试

对于远程服务器上运行的应用，可以使用以下步骤设置远程调试：

  1. 在远程服务器上安装debugpy：

    pip install debugpy

  2. 在服务器端代码中添加：

    import debugpy
debugpy.listen(("0.0.0.0", 5678))
print("等待调试器连接...")
debugpy.wait_for_client()

  3. 在本地Cursor中配置：

    {
    "name": "远程调试",
    "type": "debugpy",
    "request": "attach",
    "connect": {
        "host": "your-server-ip",
        "port": 5678
    },
    "pathMappings": [
        {
            "localRoot": "${workspaceFolder}",
            "remoteRoot": "/path/on/server"
        }
    ]
}

总结

在Cursor中配置Python调试环境并不复杂，但需要了解不同选项的用途和适用场景。通过本文介绍的配置方法，你可以为各种Python应用类型设置合适的调试环境，提高开发效率。最重要的是，选择最适合你的工作流的console选项，并根据实际需要调整其他高级选项。

配置一次后，你可以在不同项目中重复使用这些配置，只需要针对特定项目进行少量调整。希望本指南能帮助你在Cursor中获得流畅的Python调试体验！

0
工具
版权归属： EulerBlind
本文链接： https://blog.elvisiky.com/archives/exWp3nAJ
许可协议： 本文使用《署名-非商业性使用-相同方式共享 4.0 国际 (CC BY-NC-SA 4.0)》协议授权

评论区