当前位置：首页 > news >正文

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

news 2025/4/26 15:54:55

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

一、前期准备

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

安装Python（建议3.8或更高版本）
安装Cursor编辑器
安装必要的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"
}

九、实际调试操作流程

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

十、远程调试

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

在远程服务器上安装debugpy：
```
pip install debugpy
```

在服务器端代码中添加：

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

在本地Cursor中配置：

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