一、项目简介：VS Code Python 扩展
microsoft/vscode-python 是微软为 Visual Studio Code 打造的官方 Python 语言扩展，为所有仍在积极维护的 Python 版本提供丰富的语言支持。它本身是一个"外壳 + 接入点"式的扩展：把智能感知（IntelliSense，由 Pylance 提供）、调试（由 Python Debugger 提供）、格式化、Lint、代码导航、重构、变量浏览器、测试资源管理器、环境管理等能力聚合在一起，并把这些能力以可插拔的方式开放给其他扩展继续增强。仓库采用 MIT 友好的开源许可，长期由微软 Python 团队维护，是 VS Code 上下载量与使用量最高的扩展之一。无论你是写数据分析脚本、后端 Web 服务、命令行工具，还是做机器学习实验，它都能把"编辑—补全—调试—测试"这一整套 Python 开发闭环整合进编辑器。
安装该扩展后，VS Code 会自动连带安装几个可选依赖扩展以提供完整体验：Pylance（高性能 Python 语言服务）、Python Debugger（基于 debugpy 的无缝调试体验），以及较新推出的 Python Environments（专门的环境管理扩展）。这些都是可选依赖，即便它们安装失败，Python 扩展本身仍能正常工作，你也可以按需禁用或卸载。
它还把格式化与 Lint 设计为可插拔：你可以根据项目偏好选择自己喜欢的格式化器与 Linter，详见 VS Code 文档中的 选择格式化器 与 选择 Linter 指南。如果遇到某个子扩展的问题，应到对应扩展自己的仓库去反馈，而不是本仓库。
该扩展还支持在 vscode.dev（含 github.dev）这类网页版 VS Code 中以"部分模式"运行，对正在编辑的文件提供部分 IntelliSense。它支持的界面语言包括德语、英语、西班牙语、波斯语、法语、意大利语、日语、韩语、荷兰语、波兰语、葡萄牙语（巴西）、俄语、土耳其语、简体中文与繁体中文。关于数据与隐私：该扩展会收集使用数据发送给微软以改进产品，详情见微软 隐私声明，你可以通过 VS Code 的 telemetry.telemetryLevel 设置控制是否上报。
二、环境准备与前置依赖
部署这个扩展分两部分：先准备好 Python 解释器，再安装 VS Code 与扩展。
- 安装一个受支持版本的 Python（注意：macOS 上系统自带的那个 Python 不受支持，请到 python.org 或用 pyenv、conda 自行安装）；
- 安装 Visual Studio Code 桌面版（稳定版即可）；
- 可选：安装 Anaconda/Miniconda、venv、virtualenv、pipenv 或 pyenv 等环境管理工具；
- 网络环境需能访问 VS Code Marketplace（离线环境见后文 VSIX 手动安装方式）。
确认 Python 可用：
python3 --version
pip3 --version建议为每个项目单独建虚拟环境，避免污染全局解释器：
python3 -m venv .venv
# Linux/macOS
source .venv/bin/activate
# Windows PowerShell
.venv\Scripts\Activate.ps1如果使用 conda，则：
conda create -n myenv python=3.11
conda activate myenv环境激活后，VS Code 的 Python 扩展通常能自动识别到当前终端所用的环境；如果没有，仍需手动执行一次 Python: Select Interpreter。扩展支持自动激活并切换 virtualenv、venv、pipenv、conda、pyenv 等多种环境，相关细节见官方 环境管理文档。
三、部署方式一：Marketplace 在线安装（推荐）
这是最常见的方式。三步即可完成：
第 1 步：按上面说明在系统上装好受支持版本的 Python。
第 2 步：打开 VS Code，点击左侧扩展图标（或按 Ctrl+Shift+X），搜索 "Python"，找到微软官方发布的 "Python" 扩展（发布者为 Microsoft），点击 Install。安装时 Pylance、Python Debugger 等会作为可选依赖一并装上。
第 3 步：打开或新建一个 .py 文件，开始写代码即可。首次打开时扩展会自动加载语言服务，右下角可能短暂显示分析进度，等它完成后补全与诊断就会就绪。
扩展升级由 VS Code 自动检查；若想固定某个版本，可在扩展详情里关掉自动更新，再用 VSIX 方式降级。远程开发场景（WSL、SSH、Dev Container）下，Python 扩展需要安装在"远端"那一侧——通过 Remote-SSH 连接时，VS Code 会提示你在远程主机上安装扩展。
安装完成后，首先要做的是选择解释器：点击 VS Code 状态栏上的 Python 版本号，或按 Ctrl+Shift+P 执行 Python: Select Interpreter，从列表里选中你刚才建好的虚拟环境（如 .venv/bin/python）。
关于新版环境管理扩展：你可能会看到 Python Environments 扩展已被安装，但它是否"启用"由设置项 "python.useEnvironmentsExtension" 控制。设为 true 表示主动选用新扩展做环境管理；不指定时，微软会在灰度推送中随机开启，直到它成为所有用户的默认体验。该扩展仍在积极迭代中，目标是提供专门的视图与更顺手的创建、删除、切换环境以及管理包的工作流。
四、部署方式二：VSIX 离线手动安装
在无法访问 Marketplace 的内网、隔离环境或需要固定版本时，可以下载 VSIX 包手动安装。到扩展的 Marketplace 页面，点击 "Download Extension" 下载对应你系统与架构的 .vsix 文件，然后在 VS Code 扩展面板右上角的 "..." 菜单里选择 "Install from VSIX..."，选中下载的文件即可。
# 也可以用命令行安装
code --install-extension ms-python.python-xxx.vsix注意手动安装的可选依赖（Pylance、debugpy 等）需要一并下载对应 VSIX 装上，否则相关功能会缺失。安装后同样要执行 Python: Select Interpreter 选定解释器。在隔离环境中，还需把项目依赖（用 pip download -r requirements.txt -d wheels/ 下载到本地）一并拷贝，再在目标机器 pip install --no-index --find-links=wheels -r requirements.txt 离线安装。
五、调试、测试与编辑体验配置
选好解释器后，就可以配置调试器了。通过左侧"运行和调试"活动栏创建 launch.json，或直接按 F5 启动调试。
测试方面，运行命令面板里的 Python: Configure Tests，选择测试框架（unittest 或 pytest），配置完成后即可在测试资源管理器里查看、运行与调试测试。
常用命令一览（命令面板 Ctrl+Shift+P 输入即可）：
Python: Select Interpreter—— 在多个解释器、版本与环境间切换；Python: Start Terminal REPL—— 用所选解释器在 VS Code 终端启动交互式 REPL；Python: Run Python File in Terminal—— 在终端运行当前文件（也可右键文件选该项）；Python: Configure Tests—— 选择测试框架并启用测试资源管理器。
功能上，扩展提供 IntelliSense 自动补全与代码导航、基于 Pylint/Flake8 等的 Lint、基于 black/autopep/yapf 的代码格式化、脚本与 Web 应用调试、unittest/pytest 测试、Jupyter Notebook 支持、自动识别并切换 virtualenv/venv/pipenv/conda/pyenv 环境，以及变量提取、方法提取等重构能力（更深度的 import 排序等可配合 isort、Ruff 扩展）。
调试器基于开源的 debugpy，支持断点、条件断点、日志断点、变量监视、调用堆栈查看、单步步入/步出、远程附加调试以及多进程调试。Web 应用调试只需在 launch.json 里选择对应的调试配置（如 Flask、Django），填上入口与端口即可一键启动并命中断点。测试资源管理器则会自动发现项目里的测试用例，支持单独运行某个用例、重复运行失败用例以及在测试处断点调试。
在数据科学场景下，扩展还提供变量浏览器（Variable Explorer）查看 Notebook 中的变量，以及数据查看器（Data Viewer）以表格形式可视化 pandas DataFrame。配合 Jupyter 扩展，可以在单元格里加 matplotlib 绘图并直接渲染输出。更多说明见 Jupyter Notebook 支持文档。
格式化与 Lint 可以在 .vscode/settings.json 里指定，例如用 black 做格式化：
{
"editor.defaultFormatter": "ms-python.black-formatter",
"[python]": { "editor.defaultFormatter": "ms-python.black-formatter" },
"python.analysis.typeCheckingMode": "basic"
}保存时自动格式化可加上 "editor.formatOnSave": true。需要注意的是，新版 Python 扩展把 black、ruff 等做成了独立扩展，使用前需在扩展市场一并安装对应的 formatter/linter 扩展。
Jupyter Notebook 体验由 Jupyter 扩展提供：装上它之后，打开或新建一个 .ipynb 文件即可在 Notebook 编辑器里分单元格运行代码、渲染图表。
六、常见问题与 FAQ（含报错解决）
Q1：补全/跳转用不了，左下角一直转圈或提示 "No interpreter selected"？
A：这是没有选定解释器导致的。执行 Python: Select Interpreter 选中正确的虚拟环境；如果列表里没有，就用 "Enter interpreter path" 手动指向 .venv/bin/python。
Q2：导入自己写的模块报 "unresolved import"？
A：通常是项目根目录未被加入搜索路径。可在工作区 .vscode/settings.json 里设置 "python.analysis.extraPaths": ["./src"]，或确认终端里运行时的工作目录与解释器一致。
Q3：macOS 上系统 Python 为什么不被支持？
A：官方明确说明 macOS 系统自带的 Python 不受支持，因为它路径特殊、权限受限。请到 python.org 下载官方安装包，或用 pyenv/conda 安装，再在扩展里选中它。
Q4：想关掉扩展的遥测数据上报？
A：扩展会收集使用数据发送给微软以改进产品，遵循 VS Code 的 telemetry.telemetryLevel 设置。把它设为 off 即可关闭，方法见官方支持文档。
Q5：Pylance 或 Python Debugger 自动安装失败？
A：它们是可选依赖，失败不会让主扩展失效，但会缺失对应功能。手动到 Marketplace 单独安装这两个扩展，或检查网络能否访问 Marketplace。
Q6：在 vscode.dev 里为什么补全不完整？
A：网页版 vscode.dev 只提供"部分模式"支持，仅对编辑器中打开的文件提供部分 IntelliSense，完整的本地环境、调试、测试能力仍需桌面版。
Q7：调试时断点不生效、命中断点却跳到别的文件？
A：多半是调试用的解释器与你选定的解释器不一致，或 launch.json 里的 program/cwd 路径不对。打开调试面板检查所选 Python 解释器，并确认 launch.json 中 "python" 指向同一个虚拟环境的解释器。
Q8：想升级到预发布版本体验新功能怎么办？
A：在扩展面板里找到 Python 扩展，把 "Switch to Pre-release Version" 打开即可；遇到 bug 可到 Issues 反馈。正式生产环境建议使用稳定版。
Q9：扩展提示 "Python is not installed" 或找不到 python？
A：确认系统已安装 Python 且在 PATH 中（命令行执行 python3 --version 有输出）。Windows 上安装 Python 时记得勾选 "Add Python to PATH"。仍找不到时，用 Python: Select Interpreter 里的 "Enter interpreter path" 手动指定可执行文件的绝对路径。
Q10：如何完全卸载扩展？
A：在扩展面板找到 Python 扩展，选择 Uninstall，连带把 Pylance、Python Debugger、Python Environments 等一并卸载；卸载不会删除你系统上的 Python 与项目代码，只移除编辑器侧的集成。
Q11：命令面板里搜不到 Python 命令？
A：说明扩展未正确激活。先确认扩展已安装且未被禁用，再打开一个 .py 文件触发激活；仍不行时执行命令面板的 Developer: Reload Window 重启窗口。
七、总结与相关资源
VS Code Python 扩展是微软官方维护的 Python 开发入口，部署路径清晰：先装好 Python 与虚拟环境，再从 Marketplace 或 VSIX 装上扩展，最后选定解释器、按需配置调试与测试即可。它把 Pylance、Python Debugger、环境管理等能力聚合为一体，是 Python 开发者在 VS Code 里的基础底座。日常使用中，最常见的两个动作就是"选对解释器"和"把虚拟环境装好"，把这两件事做对，后续的补全、调试、测试通常都会自动工作。
部署完成后，可以通过几个动作验收：打开一个 .py 文件，确认状态栏显示了你选的解释器路径；输入 import os 后悬停在 os 上能看到文档；按 F5 能在断点处停下；测试资源管理器能发现并运行你的 pytest/unittest 用例。这几项都正常，就说明扩展与环境配置到位了。
此外，命令面板里输入 Python: 能看到数十个命令，常用的还有选择解释器、在终端启动 REPL、运行当前文件、配置测试等；输入 Jupyter: 则是 Notebook 相关命令。掌握命令面板，比在菜单里到处点要高效得多。
格式化与 Lint 的分工也值得理清：扩展本身不再内置 black、ruff 等工具，而是把它们做成独立扩展。第一次保存时若提示选择格式化器，选 black 即可；Lint 则推荐 Ruff，速度快、规则全。装好对应扩展后，在设置里把默认格式化器指向它，并开启保存时自动格式化，团队代码风格就能保持一致。
更多资料可参考：官方 Python 教程、Python 语言文档、Jupyter Notebook 文档，以及仓库的 Discussions 问答区。遇到问题请到 GitHub Issues 反馈。