Python VScode 配置

在 VS Code 中配置 Python 开发环境是一个非常标准化的过程。为了让你获得最佳的开发体验（包括代码补全、格式化、调试和虚拟环境管理），以下是截至 2026 年最主流、最高效的配置指南。

第一步：安装基础环境

1. 安装 Python：前往 Python 官网 下载并安装 Python（建议 3.10 或更高版本）。安装时务必勾选 “Add Python to PATH”。
2. 安装 VS Code：前往 VS Code 官网 下载并安装。

第二步：安装必备 VS Code 插件

打开 VS Code，点击左侧活动栏的 扩展 (Extensions) 图标（或按 Ctrl+Shift+X / Cmd+Shift+X），搜索并安装以下插件：

1. Python (发布者: Microsoft)：必备，提供核心支持、调试、Jupyter 支持和解释器管理。
2. Pylance (发布者: Microsoft)：必备，提供极速的类型检查和智能代码补全（通常安装 Python 插件时会自动推荐安装）。
3. Ruff (发布者: Astral Software)：强烈推荐。目前 Python 社区最火的工具，用 Rust 编写，速度极快，同时替代了 Black (格式化) 和 Flake8/PyLint (代码检查)。
4. Python Debugger (发布者: Microsoft)：必备，用于调试 Python 代码。
5. (可选) Jupyter：如果你需要做数据分析或运行 .ipynb 文件。
6. (可选) Python Environment Manager：更方便地在底部状态栏切换虚拟环境。

第三步：创建项目与虚拟环境 (最佳实践)

永远不要在全局环境中安装包，使用虚拟环境可以避免依赖冲突。

1. 在 VS Code 中打开你的项目文件夹：文件 -> 打开文件夹。
2. 打开终端 (Ctrl + ~ 或 Cmd + ~)。
3. 创建虚拟环境（以 venv 为例）：

   # Windows
   python -m venv .venv
   # macOS / Linux
   python3 -m venv .venv

4. 激活虚拟环境：

• Windows (CMD): .venv\Scripts\activate.bat
• Windows (PowerShell): .venv\Scripts\Activate.ps1
• macOS / Linux: source .venv/bin/activate
  (注：VS Code 通常会在你创建 .venv 文件夹后，自动提示你选择它作为工作区解释器，点击“是”即可。)

第四步：配置工作区 (settings.json)

为了让 Ruff 接管格式化和代码检查，并规范你的开发环境，建议配置项目级别的 settings.json。

1. 按 Ctrl+Shift+P (或 Cmd+Shift+P) 打开命令面板。
2. 输入并选择 Preferences: Open Workspace Settings (JSON)（首选项：打开工作区设置 (JSON)）。
3. 粘贴以下配置（可根据需要调整）：

{
    // 1. 指定 Python 解释器路径 (VS Code 通常会自动生成，如果没有可手动指定)
    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/Scripts/python.exe", // Windows
    // "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python", // macOS/Linux

    // 2. 配置 Ruff 作为默认的格式化和 Linting 工具
    "[python]": {
        "editor.defaultFormatter": "charliermarsh.ruff",
        "editor.formatOnSave": true,
        "editor.codeActionsOnSave": {
            "source.fixAll": "explicit",
            "source.organizeImports": "explicit"
        }
    },

    // 3. Ruff 特定配置 (可选)
    "ruff.lint.args": [
        "--ignore=E501" // 示例：忽略单行过长警告
    ],

    // 4. 终端设置：确保新终端自动激活虚拟环境
    "python.terminal.activateEnvironment": true,

    // 5. 文件排除：避免搜索和索引虚拟环境中的文件，提升性能
    "files.watcherExclude": {
        "**/.venv/**": true
    },
    "search.exclude": {
        "**/.venv/**": true
    }
}

(注意：如果是 macOS/Linux，请将 Scripts 改为 bin)

第五步：配置运行与调试 (launch.json)

如果你需要按 F5 调试代码，可以配置启动文件。

1. 点击左侧活动栏的 运行和调试 图标（或按 Ctrl+Shift+D）。
2. 点击 创建 launch.json 文件，选择 Python 文件。
3. VS Code 会在 .vscode 目录下生成 launch.json，你可以修改为类似如下配置：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: 当前文件",
            "type": "debugpy",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "justMyCode": true, // 设为 false 可以调试进入第三方库源码
            "env": {
                "PYTHONPATH": "${workspaceFolder}" // 确保能正确导入项目内的模块
            }
        },
        {
            "name": "Python: 运行特定模块 (如 main.py)",
            "type": "debugpy",
            "request": "launch",
            "module": "main", // 替换为你的入口模块名
            "console": "integratedTerminal"
        }
    ]
}

第六步：验证配置是否成功

1. 新建一个 test.py 文件。
2. 输入以下代码：

   import os

   def hello_world(name: str) -> str:
       return f"Hello, {name}!"

   print(hello_world("VS Code"))

3. 测试格式化：保存文件 (Ctrl+S)，代码应该会自动格式化（如果没触发，右键选择“格式化文档”）。
4. 测试 Linting：故意删掉 import os，Ruff 应该会立刻在 os 下方画出波浪线，提示未使用的导入或错误。
5. 测试运行：点击右上角的 ▶️ (运行) 按钮，或按 F5，下方终端应输出 Hello, VS Code!，且终端提示符前带有 (.venv)。

💡 进阶技巧与常见问题

1. 右下角解释器没显示 .venv？

• 按 Ctrl+Shift+P，输入 Python: Select Interpreter，手动选择你项目下的 .venv 路径。

1. 为什么安装了包，VS Code 还是提示 “Import 找不到”？

• 99% 的情况是因为 VS Code 当前使用的解释器不是你安装了包的那个虚拟环境。检查右下角的 Python 版本路径是否正确。

1. 使用 requirements.txt 或 pyproject.toml？

• 现代 Python 项目推荐使用 pyproject.toml 管理依赖。你可以在其中直接配置 Ruff 规则，VS Code 插件会自动读取。

1. 远程开发 (WSL / SSH / Dev Containers)

• 如果你在 Windows 上开发但需要 Linux 环境，强烈建议安装 WSL 插件，在 WSL 中打开文件夹，上述所有配置步骤完全一致，且体验无缝。

按照以上步骤配置，你将获得一个现代化、极速且规范的 Python 开发环境。如果有特定框架（如 Django, FastAPI, PyTorch）的配置需求，可以告诉我，我为你提供针对性的补充配置！