简介这份资源面向希望在 VSCode 中搭建 Python 开发环境的开发者尤其适合刚接触编辑器配置、需要一套完整参考模板的初学者与进阶用户。内容围绕 Python 开发环境的配置展开涵盖编辑器设置、插件配置、调试与运行环境等常见需求帮助读者快速完成从零到可用的环境搭建。压缩包共 152 个文件约 3.54MB以 tmpl 模板文件为主辅以 ts、json、yml、cfg 等配置文件以及 gif、png 演示素材和 md 说明文档另含 py、js、cpp、rs、php 等多语言示例文件便于对照不同场景理解配置项。目前已有 1396 人学习下载说明该配置方案具备一定参考价值。读者可从中获取完整的配置模板、目录结构示例与多语言测试文件用于快速复现开发环境、排查配置问题并作为日常 VSCode 工作区设置的参考底稿。1. 从一台裸机到能跑 Python为什么我劝你先别急着装插件很多人第一次在 VS Code 里配 Python 环境都是被“插件市场里搜 Python点安装然后发现代码还是跑不起来”这套流程坑过的。我见过太多人卡在“明明装了 Python 扩展为什么终端里python命令找不到”这种问题上。VS Code 本身只是一个编辑器它不附带 Python 解释器也不自带虚拟环境管理能力。你要做的第一件事是把“编辑器”和“运行时”这两层彻底分开理解。这篇笔记拆的是 2024 年仍然适用的一套配置流程覆盖从解释器安装、扩展选择、虚拟环境绑定到调试配置和常见报错排查。适合刚接触 Python 的新手也适合从 PyCharm 或 Jupyter 迁过来、想把 VS Code 调顺手的老手。下面按我实际配一台新机器的顺序来写每一步都给出可复现的命令和参数说明。2. 解释器与扩展先把地基打对再谈代码补全2.1 解释器安装别用系统自带的那个Windows 上很多人直接去微软商店装 Python或者用系统预装的版本。常见做法是去 python.org 下载对应系统的安装包安装时勾选“Add python.exe to PATH”。这个勾选决定了你后面在 VS Code 终端里能不能直接敲python命令。macOS 上系统自带的/usr/bin/python3是给系统工具用的版本旧且不建议动。我一般用 Homebrew 装一个独立版本# macOS 上用 Homebrew 安装 Python 3.12 brew install python3.12 # 确认安装路径和版本 which python3.12 python3.12 --versionLinux 上同理优先用发行版包管理器装但要注意有些发行版会把python指向 Python 2所以显式用python3更稳妥。安装完成后在终端里执行python --version或python3 --version能输出版本号才算地基打好了。如果这一步就报“command not found”后面所有 VS Code 配置都是空中楼阁。2.2 VS Code 扩展只装必要的别堆一屏打开 VS Code左侧扩展面板搜索 Python排第一的那个由 Microsoft 发布的 Python 扩展是必装的。它捆绑了 Pylance语言服务器、调试器、测试适配器等组件。2024 年这个扩展已经相当重装完之后你会看到资源管理器里多出测试、Jupyter 等面板。如果你不写 Notebook可以在设置里把 Jupyter 相关功能关掉减少启动开销。除了 Python 扩展我一般还会装这几个Pylance通常随 Python 扩展自动安装负责类型推断和补全。如果没自动装手动搜一下。Ruff新一代 linter 和 formatter比 flake8 black 组合快很多。扩展市场搜 Ruff装 astral-sh 那个。Even Better TOML如果你用pyproject.toml管理项目配置这个扩展让 TOML 文件有语法高亮和校验。装完扩展后按CtrlShiftPmacOS 是CmdShiftP打开命令面板输入Python: Select Interpreter你会看到 VS Code 自动扫描到的解释器列表。如果列表里没有你刚装的那个版本说明 PATH 没配好或者解释器装在了非标准路径。这时候可以手动输入路径比如~/opt/python3.12/bin/python3.12。注意选解释器这一步只是告诉 VS Code 用哪个 Python 来跑当前工作区的代码它不会改变系统默认的python命令指向。两者是独立的。2.3 虚拟环境每个项目一个别偷懒全局装包是万恶之源。不同项目依赖同一个包的不同版本时全局环境必然打架。我习惯在每个项目根目录下建一个.venv目录# 在项目根目录创建虚拟环境 python3.12 -m venv .venv # 激活虚拟环境Windows .venv\Scripts\activate # 激活虚拟环境macOS/Linux source .venv/bin/activate # 激活后安装依赖 pip install requests pandas创建完成后回到 VS Code再次执行Python: Select Interpreter这次要选.venv目录下的那个解释器。选对之后VS Code 底部状态栏会显示当前解释器路径。你新建一个.py文件敲import pandas如果 pandas 只装在.venv里补全和跳转应该正常工作。如果补全不出来多半是解释器选错了或者 Pylance 还在索引中等几秒或重启窗口。这里有个参数值得留意python -m venv默认不包含系统站点包。如果你确实需要继承全局包可以加--system-site-packages但我强烈不建议这么做虚拟环境的意义就是隔离。另外.venv目录记得写进.gitignore别提交到仓库。3. 调试与任务配置让 F5 真正跑起来3.1 launch.json调试配置的核心文件VS Code 的调试行为由.vscode/launch.json控制。第一次按 F5 时如果没有这个文件VS Code 会提示你选择调试器类型选 Python File 后会生成一个默认配置。但默认配置往往不够用比如你想传命令行参数、设置环境变量、指定工作目录都需要手动改。下面是我常用的一个launch.json模板{ version: 0.2.0, configurations: [ { name: Python: 当前文件, type: debugpy, request: launch, program: ${file}, console: integratedTerminal, cwd: ${workspaceFolder}, env: { PYTHONPATH: ${workspaceFolder}/src }, args: [--verbose], justMyCode: true } ] }逐项说明type在 2024 年已经统一为debugpy老版本用的python类型已被弃用。program里的${file}表示调试当前打开的文件如果你固定调试某个入口文件可以写成${workspaceFolder}/main.py。console设为integratedTerminal后input()这类交互函数才能正常工作默认的internalConsole不支持标准输入。cwd是工作目录影响相对路径的解析。env里可以注入环境变量比如把src目录加进PYTHONPATH这样import自己的模块时不会报找不到。args是传给脚本的命令行参数按需改。justMyCode设为true时调试器会跳过第三方库的内部代码只停在你自己的代码里如果你要追进库函数改成false。3.2 tasks.json把重复命令固化下来如果你经常要跑测试、格式化、lint可以配.vscode/tasks.json用CtrlShiftB一键触发。比如一个跑 pytest 的任务{ version: 2.0.0, tasks: [ { label: pytest, type: shell, command: ${workspaceFolder}/.venv/bin/python, args: [-m, pytest, -v, tests/], group: { kind: build, isDefault: true }, problemMatcher: [] } ] }这里command直接指向虚拟环境里的 Python避免激活环境这一步。args里-m pytest确保用的是当前解释器对应的 pytest 模块而不是全局的。group设为默认构建任务后CtrlShiftB就会直接跑这个任务。problemMatcher留空是因为 pytest 的输出格式默认不被 VS Code 解析成问题列表如果你想要错误跳转可以装 pytest 的 problem matcher 扩展或自定义正则。3.3 settings.json工作区级别的偏好设置有些设置我习惯放在工作区的.vscode/settings.json里而不是全局用户设置。这样换项目时不会互相干扰。比如{ python.defaultInterpreterPath: ${workspaceFolder}/.venv/bin/python, python.terminal.activateEnvironment: true, editor.formatOnSave: true, editor.codeActionsOnSave: { source.organizeImports: explicit }, [python]: { editor.defaultFormatter: charliermarsh.ruff } }python.defaultInterpreterPath指定默认解释器避免每次打开项目都要手动选。python.terminal.activateEnvironment设为true后VS Code 打开终端时会自动激活虚拟环境省去手动source的步骤。editor.formatOnSave配合 Ruff 扩展保存时自动格式化。source.organizeImports设为explicit表示保存时自动整理 import 顺序这个在 2024 年的 VS Code 版本里需要显式指定老版本用的true已经不再推荐。4. 避坑与排查那些让你怀疑人生的报错4.1 终端里python命令找不到现象VS Code 集成终端里敲python提示“command not found”但系统终端里正常。原因VS Code 启动时继承的环境变量可能和登录 shell 不一致尤其在 macOS 上GUI 应用不会读取.zshrc或.bash_profile。解决在 VS Code 设置里搜terminal.integrated.env.osx手动把 PATH 补进去或者更简单在settings.json里设python.terminal.activateEnvironment: true让 VS Code 用选定的解释器路径去激活环境绕过 PATH 问题。4.2 Pylance 报“Import could not be resolved”现象代码能跑但编辑器里import requests下面有黄色波浪线提示无法解析。原因Pylance 用的解释器和终端里跑代码的解释器不是同一个或者包装在全局而 Pylance 在虚拟环境里找。解决CtrlShiftP执行Python: Select Interpreter确认选中的是装了该包的那个环境。如果确认无误执行Python: Restart Language Server强制 Pylance 重新索引。还不行就检查python.analysis.extraPaths设置把额外的包路径加进去。4.3 调试时断点变成灰色空心圆现象在代码行号左侧点断点显示灰色空心圆F5 启动后不停。原因launch.json里的program指向的文件和你当前编辑的文件不一致或者justMyCode设为了true而断点打在第三方库里。解决检查program字段是否用了${file}或正确的入口路径。如果断点在库代码里把justMyCode改成false。另外如果代码是通过exec或动态导入运行的调试器可能无法映射断点这种情况需要改用debugpy的远程附加模式。4.4 虚拟环境激活后 pip 装包仍然装到全局现象明明激活了.venvpip install之后包却出现在全局 site-packages 里。原因pip命令指向的不是虚拟环境里的 pip可能是 PATH 里全局 pip 优先级更高或者虚拟环境创建时用了--system-site-packages。解决激活环境后执行which pipWindows 用where pip确认路径在.venv目录下。如果不是用python -m pip install代替直接调pip这样一定用的是当前解释器对应的 pip。创建环境时避免加--system-site-packages。4.5 保存时格式化把代码改乱现象editor.formatOnSave开启后保存时 Ruff 或 Black 把代码格式改得和团队规范不一致。原因格式化工具版本或配置与项目要求不匹配或者同时装了多个 formatter 导致冲突。解决在settings.json里显式指定[python]的editor.defaultFormatter只保留一个。如果项目有pyproject.toml确保 Ruff 或 Black 读取的是项目根目录的配置而不是用户全局配置。可以在输出面板选 Ruff 查看它实际用的配置文件路径。5. 进阶技巧用 Dev Container 把环境锁死如果你受够了“我这能跑你那报错”的扯皮可以试试 VS Code 的 Dev Container 功能。它把整个开发环境塞进一个 Docker 容器解释器、依赖、扩展全部声明在.devcontainer/devcontainer.json里。团队里每个人打开项目时VS Code 会自动构建容器并在里面开发环境差异被彻底消除。一个最小化的devcontainer.json长这样{ name: Python 3.12, image: mcr.microsoft.com/devcontainers/python:3.12, postCreateCommand: pip install -r requirements.txt, customizations: { vscode: { extensions: [ms-python.python, charliermarsh.ruff] } } }image指定基础镜像微软维护的 Python 镜像已经预装了常用工具。postCreateCommand在容器创建后自动跑用来装项目依赖。customizations.vscode.extensions声明容器内自动安装的扩展这样队友打开时不需要手动装。整个配置提交到仓库后任何人 clone 下来用 VS Code 打开选“Reopen in Container”几分钟后就能得到一个完全一致的环境。这个方案的门槛是本地要装 Docker且首次构建镜像需要下载几百 MB。但一旦跑通后面换机器、换系统、加新人成本几乎为零。我现在的习惯是个人小脚本用本地.venv就够了但凡是要多人协作或长期维护的项目一律上 Dev Container。从那以后我每次开新项目第一件事就是先把.devcontainer目录建好再写第一行代码。希望帮到你。本文还有配套的精品资源点击获取
简介这份资源面向希望在 VSCode 中搭建 Python 开发环境的开发者尤其适合刚接触编辑器配置、需要一套完整参考模板的初学者与进阶用户。内容围绕 Python 开发环境的配置展开涵盖编辑器设置、插件配置、调试与运行环境等常见需求帮助读者快速完成从零到可用的环境搭建。压缩包共 152 个文件约 3.54MB以 tmpl 模板文件为主辅以 ts、json、yml、cfg 等配置文件以及 gif、png 演示素材和 md 说明文档另含 py、js、cpp、rs、php 等多语言示例文件便于对照不同场景理解配置项。目前已有 1396 人学习下载说明该配置方案具备一定参考价值。读者可从中获取完整的配置模板、目录结构示例与多语言测试文件用于快速复现开发环境、排查配置问题并作为日常 VSCode 工作区设置的参考底稿。1. 从一台裸机到能跑 Python为什么我劝你先别急着装插件很多人第一次在 VS Code 里配 Python 环境都是被“插件市场里搜 Python点安装然后发现代码还是跑不起来”这套流程坑过的。我见过太多人卡在“明明装了 Python 扩展为什么终端里python命令找不到”这种问题上。VS Code 本身只是一个编辑器它不附带 Python 解释器也不自带虚拟环境管理能力。你要做的第一件事是把“编辑器”和“运行时”这两层彻底分开理解。这篇笔记拆的是 2024 年仍然适用的一套配置流程覆盖从解释器安装、扩展选择、虚拟环境绑定到调试配置和常见报错排查。适合刚接触 Python 的新手也适合从 PyCharm 或 Jupyter 迁过来、想把 VS Code 调顺手的老手。下面按我实际配一台新机器的顺序来写每一步都给出可复现的命令和参数说明。2. 解释器与扩展先把地基打对再谈代码补全2.1 解释器安装别用系统自带的那个Windows 上很多人直接去微软商店装 Python或者用系统预装的版本。常见做法是去 python.org 下载对应系统的安装包安装时勾选“Add python.exe to PATH”。这个勾选决定了你后面在 VS Code 终端里能不能直接敲python命令。macOS 上系统自带的/usr/bin/python3是给系统工具用的版本旧且不建议动。我一般用 Homebrew 装一个独立版本# macOS 上用 Homebrew 安装 Python 3.12 brew install python3.12 # 确认安装路径和版本 which python3.12 python3.12 --versionLinux 上同理优先用发行版包管理器装但要注意有些发行版会把python指向 Python 2所以显式用python3更稳妥。安装完成后在终端里执行python --version或python3 --version能输出版本号才算地基打好了。如果这一步就报“command not found”后面所有 VS Code 配置都是空中楼阁。2.2 VS Code 扩展只装必要的别堆一屏打开 VS Code左侧扩展面板搜索 Python排第一的那个由 Microsoft 发布的 Python 扩展是必装的。它捆绑了 Pylance语言服务器、调试器、测试适配器等组件。2024 年这个扩展已经相当重装完之后你会看到资源管理器里多出测试、Jupyter 等面板。如果你不写 Notebook可以在设置里把 Jupyter 相关功能关掉减少启动开销。除了 Python 扩展我一般还会装这几个Pylance通常随 Python 扩展自动安装负责类型推断和补全。如果没自动装手动搜一下。Ruff新一代 linter 和 formatter比 flake8 black 组合快很多。扩展市场搜 Ruff装 astral-sh 那个。Even Better TOML如果你用pyproject.toml管理项目配置这个扩展让 TOML 文件有语法高亮和校验。装完扩展后按CtrlShiftPmacOS 是CmdShiftP打开命令面板输入Python: Select Interpreter你会看到 VS Code 自动扫描到的解释器列表。如果列表里没有你刚装的那个版本说明 PATH 没配好或者解释器装在了非标准路径。这时候可以手动输入路径比如~/opt/python3.12/bin/python3.12。注意选解释器这一步只是告诉 VS Code 用哪个 Python 来跑当前工作区的代码它不会改变系统默认的python命令指向。两者是独立的。2.3 虚拟环境每个项目一个别偷懒全局装包是万恶之源。不同项目依赖同一个包的不同版本时全局环境必然打架。我习惯在每个项目根目录下建一个.venv目录# 在项目根目录创建虚拟环境 python3.12 -m venv .venv # 激活虚拟环境Windows .venv\Scripts\activate # 激活虚拟环境macOS/Linux source .venv/bin/activate # 激活后安装依赖 pip install requests pandas创建完成后回到 VS Code再次执行Python: Select Interpreter这次要选.venv目录下的那个解释器。选对之后VS Code 底部状态栏会显示当前解释器路径。你新建一个.py文件敲import pandas如果 pandas 只装在.venv里补全和跳转应该正常工作。如果补全不出来多半是解释器选错了或者 Pylance 还在索引中等几秒或重启窗口。这里有个参数值得留意python -m venv默认不包含系统站点包。如果你确实需要继承全局包可以加--system-site-packages但我强烈不建议这么做虚拟环境的意义就是隔离。另外.venv目录记得写进.gitignore别提交到仓库。3. 调试与任务配置让 F5 真正跑起来3.1 launch.json调试配置的核心文件VS Code 的调试行为由.vscode/launch.json控制。第一次按 F5 时如果没有这个文件VS Code 会提示你选择调试器类型选 Python File 后会生成一个默认配置。但默认配置往往不够用比如你想传命令行参数、设置环境变量、指定工作目录都需要手动改。下面是我常用的一个launch.json模板{ version: 0.2.0, configurations: [ { name: Python: 当前文件, type: debugpy, request: launch, program: ${file}, console: integratedTerminal, cwd: ${workspaceFolder}, env: { PYTHONPATH: ${workspaceFolder}/src }, args: [--verbose], justMyCode: true } ] }逐项说明type在 2024 年已经统一为debugpy老版本用的python类型已被弃用。program里的${file}表示调试当前打开的文件如果你固定调试某个入口文件可以写成${workspaceFolder}/main.py。console设为integratedTerminal后input()这类交互函数才能正常工作默认的internalConsole不支持标准输入。cwd是工作目录影响相对路径的解析。env里可以注入环境变量比如把src目录加进PYTHONPATH这样import自己的模块时不会报找不到。args是传给脚本的命令行参数按需改。justMyCode设为true时调试器会跳过第三方库的内部代码只停在你自己的代码里如果你要追进库函数改成false。3.2 tasks.json把重复命令固化下来如果你经常要跑测试、格式化、lint可以配.vscode/tasks.json用CtrlShiftB一键触发。比如一个跑 pytest 的任务{ version: 2.0.0, tasks: [ { label: pytest, type: shell, command: ${workspaceFolder}/.venv/bin/python, args: [-m, pytest, -v, tests/], group: { kind: build, isDefault: true }, problemMatcher: [] } ] }这里command直接指向虚拟环境里的 Python避免激活环境这一步。args里-m pytest确保用的是当前解释器对应的 pytest 模块而不是全局的。group设为默认构建任务后CtrlShiftB就会直接跑这个任务。problemMatcher留空是因为 pytest 的输出格式默认不被 VS Code 解析成问题列表如果你想要错误跳转可以装 pytest 的 problem matcher 扩展或自定义正则。3.3 settings.json工作区级别的偏好设置有些设置我习惯放在工作区的.vscode/settings.json里而不是全局用户设置。这样换项目时不会互相干扰。比如{ python.defaultInterpreterPath: ${workspaceFolder}/.venv/bin/python, python.terminal.activateEnvironment: true, editor.formatOnSave: true, editor.codeActionsOnSave: { source.organizeImports: explicit }, [python]: { editor.defaultFormatter: charliermarsh.ruff } }python.defaultInterpreterPath指定默认解释器避免每次打开项目都要手动选。python.terminal.activateEnvironment设为true后VS Code 打开终端时会自动激活虚拟环境省去手动source的步骤。editor.formatOnSave配合 Ruff 扩展保存时自动格式化。source.organizeImports设为explicit表示保存时自动整理 import 顺序这个在 2024 年的 VS Code 版本里需要显式指定老版本用的true已经不再推荐。4. 避坑与排查那些让你怀疑人生的报错4.1 终端里python命令找不到现象VS Code 集成终端里敲python提示“command not found”但系统终端里正常。原因VS Code 启动时继承的环境变量可能和登录 shell 不一致尤其在 macOS 上GUI 应用不会读取.zshrc或.bash_profile。解决在 VS Code 设置里搜terminal.integrated.env.osx手动把 PATH 补进去或者更简单在settings.json里设python.terminal.activateEnvironment: true让 VS Code 用选定的解释器路径去激活环境绕过 PATH 问题。4.2 Pylance 报“Import could not be resolved”现象代码能跑但编辑器里import requests下面有黄色波浪线提示无法解析。原因Pylance 用的解释器和终端里跑代码的解释器不是同一个或者包装在全局而 Pylance 在虚拟环境里找。解决CtrlShiftP执行Python: Select Interpreter确认选中的是装了该包的那个环境。如果确认无误执行Python: Restart Language Server强制 Pylance 重新索引。还不行就检查python.analysis.extraPaths设置把额外的包路径加进去。4.3 调试时断点变成灰色空心圆现象在代码行号左侧点断点显示灰色空心圆F5 启动后不停。原因launch.json里的program指向的文件和你当前编辑的文件不一致或者justMyCode设为了true而断点打在第三方库里。解决检查program字段是否用了${file}或正确的入口路径。如果断点在库代码里把justMyCode改成false。另外如果代码是通过exec或动态导入运行的调试器可能无法映射断点这种情况需要改用debugpy的远程附加模式。4.4 虚拟环境激活后 pip 装包仍然装到全局现象明明激活了.venvpip install之后包却出现在全局 site-packages 里。原因pip命令指向的不是虚拟环境里的 pip可能是 PATH 里全局 pip 优先级更高或者虚拟环境创建时用了--system-site-packages。解决激活环境后执行which pipWindows 用where pip确认路径在.venv目录下。如果不是用python -m pip install代替直接调pip这样一定用的是当前解释器对应的 pip。创建环境时避免加--system-site-packages。4.5 保存时格式化把代码改乱现象editor.formatOnSave开启后保存时 Ruff 或 Black 把代码格式改得和团队规范不一致。原因格式化工具版本或配置与项目要求不匹配或者同时装了多个 formatter 导致冲突。解决在settings.json里显式指定[python]的editor.defaultFormatter只保留一个。如果项目有pyproject.toml确保 Ruff 或 Black 读取的是项目根目录的配置而不是用户全局配置。可以在输出面板选 Ruff 查看它实际用的配置文件路径。5. 进阶技巧用 Dev Container 把环境锁死如果你受够了“我这能跑你那报错”的扯皮可以试试 VS Code 的 Dev Container 功能。它把整个开发环境塞进一个 Docker 容器解释器、依赖、扩展全部声明在.devcontainer/devcontainer.json里。团队里每个人打开项目时VS Code 会自动构建容器并在里面开发环境差异被彻底消除。一个最小化的devcontainer.json长这样{ name: Python 3.12, image: mcr.microsoft.com/devcontainers/python:3.12, postCreateCommand: pip install -r requirements.txt, customizations: { vscode: { extensions: [ms-python.python, charliermarsh.ruff] } } }image指定基础镜像微软维护的 Python 镜像已经预装了常用工具。postCreateCommand在容器创建后自动跑用来装项目依赖。customizations.vscode.extensions声明容器内自动安装的扩展这样队友打开时不需要手动装。整个配置提交到仓库后任何人 clone 下来用 VS Code 打开选“Reopen in Container”几分钟后就能得到一个完全一致的环境。这个方案的门槛是本地要装 Docker且首次构建镜像需要下载几百 MB。但一旦跑通后面换机器、换系统、加新人成本几乎为零。我现在的习惯是个人小脚本用本地.venv就够了但凡是要多人协作或长期维护的项目一律上 Dev Container。从那以后我每次开新项目第一件事就是先把.devcontainer目录建好再写第一行代码。希望帮到你。本文还有配套的精品资源点击获取
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
