VS Code Python开发环境重建：venv、Ruff与Jupyter Interactive Window深度整合-二趣网

1. 这不是“装个插件就完事”的配置，而是Python开发环境的底层重建

你搜过“VS Code配置Python”，点开前十个结果，大概率看到的是：打开扩展市场→搜Python→点安装→Ctrl+Shift+P→选Python Interpreter→选个路径→搞定。我试过这种流程，也教过不下二十个刚转行的朋友照着做，结果呢？三天后有人来问：“为什么import pandas报错？”“为什么Jupyter单元格点了没反应？”“为什么调试时断点根本不停？”——问题全出在那“一步到位”的幻觉里。

真实情况是：VS Code本身不带Python能力，它只是一个高度可定制的编辑器壳子；Python解释器、包管理器、格式化工具、静态检查器、Jupyter内核、调试器……这些全是你手动拼装的零件。它们之间不是简单“能用就行”，而是存在版本兼容链、路径解析逻辑、进程通信协议、环境隔离机制等一整套隐性规则。比如Ruff要求Python 3.8+才能启用全部规则，但你系统里默认的python命令可能指向3.7；Jupyter Interactive Window依赖IPython内核，而IPython又依赖特定版本的traitlets和jedi，稍有错配就会卡在“正在启动内核”；更隐蔽的是Windows下PATH环境变量的继承顺序——VS Code从开始菜单启动时读的是用户PATH，但从命令行code .启动时读的是shell的PATH，两者可能完全不同。

所以这篇内容不叫“VS Code Python配置教程”，它是一份Python开发环境诊断与重建手册。核心关键词就是你热搜里反复出现的四个锚点：VS Code、Python、Ruff、Jupyter Interactive Window——它们不是孤立功能，而是构成现代Python工作流的四根支柱。适合三类人：刚装完VS Code发现啥都跑不了的新手；用了一年总被莫名其妙报错困扰的中级使用者；以及想把团队开发环境标准化的项目负责人。接下来所有操作，我都基于Windows 10/11 + Python 3.11（官方CPython）+ VS Code 1.85实测，每一步都有原理说明和避坑提示，不是复制粘贴就能跑通的流水线，而是让你真正理解“为什么必须这样配”。

2. 环境设计逻辑：为什么放弃conda，坚持venv + pip + pyenv-win组合

很多人一上来就推荐conda，理由很充分：环境隔离好、包依赖自动解，还能管R语言。但我在给金融量化团队做开发环境标准化时踩过坑：conda install pandas会默认装mkl优化版，而某些C扩展模块（比如ta-lib）编译时链接的是openblas，运行时报“undefined symbol: cblas_sgemm”；更麻烦的是conda-forge和anaconda主频道的包版本策略不同，同一个yml文件在不同机器上conda env create出来的环境，numpy版本可能差小数点后两位，导致数值计算结果微差——这在回测系统里是致命的。

所以我现在所有Python项目都回归CPython原生生态：pyenv-win管理Python版本 → venv创建隔离环境 → pip安装包 → Ruff做代码规范 → Jupyter Interactive Window做交互式分析。这个链条的每个环节都可控、可审计、可复现。比如pyenv-win不是简单切换python.exe，它通过修改Windows注册表的AppExecutionAlias（应用执行别名）来劫持python命令，比修改PATH更干净；venv生成的Scripts/activate.bat里明确写死了python.exe绝对路径，避免虚拟环境激活后还调用到全局Python；pip install时加--no-cache-dir参数，防止pip缓存里混入旧版本wheel包导致安装失败。

关键决策点在于环境隔离粒度。有人用一个全局venv配所有项目，有人每个项目建独立venv。我选后者，因为Python包的ABI兼容性极差——比如你用PyTorch 2.1.0训练模型，升级到2.2.0后torch.compile()的API就变了，如果两个项目共用venv，改一个就崩另一个。而VS Code的Python扩展能自动识别项目根目录下的.venv文件夹，无需手动选择解释器，这才是真正的“开箱即用”。

再看Ruff和Jupyter的定位。Ruff不是替代flake8+black+isort的“更快版本”，它是用Rust重写的单二进制文件，启动速度比Python写的工具快10倍以上，这对VS Code的实时检查至关重要——你敲完一行代码，Ruff要在200ms内给出反馈，否则编辑体验会卡顿。而Jupyter Interactive Window不是Notebook的简化版，它是VS Code原生集成的REPL增强器：支持多行编辑、变量查看器、绘图内嵌、断点调试，甚至能直接调用当前文件里的函数——这些能力需要VS Code的调试协议（DAP）和Jupyter内核深度耦合，不是简单起个jupyter server就能实现的。

3. 核心细节拆解：从Python安装到Ruff规则落地的七层穿透

3.1 Python安装：为什么必须用官方installer而非Microsoft Store版

Windows上装Python，微软商店里那个“Python 3.11”看起来最省事，点安装就完事。但实测发现它有个致命缺陷：安装路径固定为%LOCALAPPDATA%\Packages\PythonSoftwareFoundation.Python.3.11_qbz5n2kfra8p0\LocalCache\local-packages\Python311\site-packages，而VS Code的Python扩展在扫描解释器时，会跳过所有含空格和特殊字符的路径。更麻烦的是，这个版本的pip install --user会把包装到用户目录，但venv创建的环境却找不到这些包——因为venv默认不继承--user路径。

所以必须用python.org下载的Windows x86-64 MSI安装器。安装时勾选“Add Python to PATH”和“Download debug symbols and binaries”，前者确保cmd里能直接用python命令，后者让pdb调试器能加载符号文件。重点来了：安装路径必须不含空格和中文。我见过太多人装在C:\Program Files\Python311，结果VS Code报错“无法启动调试器：path not found”。正确做法是自定义路径为C:\py311，这样所有后续路径都是纯ASCII，彻底规避Windows的8.3短文件名兼容问题。

验证安装是否成功，不要只看python --version，要运行：

python -c "import sys; print(sys.executable)"

输出必须是C:\py311\python.exe这样的绝对路径。如果显示C:\Users\XXX\AppData\Local\Microsoft\WindowsApps\python.exe，说明你装的是商店版，得卸载重装。

3.2 pyenv-win：版本切换的隐形开关

pyenv-win不是必须的，但当你需要同时维护Python 3.9（跑老项目）、3.11（新项目）、3.12（尝鲜）时，它就变成刚需。安装方式很简单：管理员权限运行PowerShell，执行：

Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1"

安装后重启终端，运行pyenv --version确认。关键配置在$HOME\.pyenv\pyenv-win\versions目录下——这里就是所有Python版本的存放地。比如pyenv install 3.11.7会下载并解压到versions\3.11.7，然后pyenv global 3.11.7会让全局python命令指向这个版本。

但VS Code不认pyenv的shim机制（即通过shell函数拦截python命令），所以必须在VS Code设置里显式指定Python路径。打开设置（Ctrl+,），搜索“python.defaultInterpreterPath”，填入C:\Users\你的用户名\.pyenv\pyenv-win\versions\3.11.7\python.exe。注意：这个路径必须精确到.exe文件，不能只写到versions\3.11.7目录。

3.3 venv创建：为什么不用virtualenv，而用原生venv

virtualenv是第三方包，venv是Python 3.3+内置模块。区别在于venv创建的环境更轻量——它不复制python.exe，而是用硬链接指向原Python安装目录的python.exe，节省磁盘空间；更重要的是，venv生成的Scripts\Activate.ps1脚本里，$env:VIRTUAL_ENV变量设置更可靠，不会像virtualenv那样在PowerShell里偶尔失效。

创建命令很简单：

python -m venv .venv

但关键在激活时机。很多教程说“先激活再pip install”，这是错的。正确流程是：创建venv → 直接pip install（不激活）→ VS Code自动识别。因为VS Code的Python扩展会扫描项目根目录下的.venv文件夹，并读取.venv\pyvenv.cfg里的home = C:\py311字段，从而知道这个venv基于哪个Python版本。如果你先activate再install，pip会把包装到激活后的site-packages，但VS Code可能因路径缓存没刷新而找不到。

验证venv是否生效，看VS Code右下角状态栏：应该显示“Python 3.11.7 (.\venv)”，括号里的.\venv表示当前激活的虚拟环境。如果显示“Python 3.11.7”，说明没识别到venv。

3.4 Ruff配置：从零开始写ruff.toml的六个必填项

Ruff的配置文件ruff.toml不是可选的，它是代码质量的守门员。很多人以为装了Ruff插件就自动生效，其实默认只开基础检查（E、F系列），像类型注解（ANN）、性能优化（PERF）、安全漏洞（S）全关着。我的ruff.toml核心六项：

src = ["src", "tests"]：指定扫描源码目录，避免检查venv或build目录
line-length = 88：遵循Black的默认换行长度，和团队代码风格对齐
select = ["E", "F", "I", "B", "ANN", "SIM", "PERF"]：启用错误、格式、导入、bug、类型、简化、性能七大类规则
ignore = ["E501", "ANN201"]：忽略行过长警告（交给Black处理）和公共函数缺少类型注解（内部工具函数可放宽）
[tool.ruff.per-file-ignores]：按文件忽略特定规则，比如"__init__.py" = ["F401"]（允许未使用导入）
[tool.ruff.mccabe]：圈复杂度阈值设为10，超过就标红提醒重构

特别注意[tool.ruff.pydocstyle]段——如果你用Google风格文档字符串，必须加convention = "google"，否则Ruff会按PEP 257的strict模式报错。还有个隐藏坑：Ruff默认不检查.pyi类型存根文件，要加extend-exclude = ["*.pyi"]才能覆盖。

3.5 Jupyter Interactive Window：内核选择的三个致命误区

Jupyter Interactive Window的内核（kernel）不是随便选的。常见误区：

误区一：选“Python 3.11.7”而不是“Python 3.11.7 (.venv)”
前者指向全局Python，后者才指向项目venv。选错会导致import的包全是全局安装的，和项目requirements.txt对不上。
误区二：用pip install jupyter后直接启动
这样装的jupyter包会把内核注册到用户目录，但VS Code的Interactive Window需要内核在venv里。正确做法是：先激活venv（或确保在venv里），再pip install ipykernel，然后python -m ipykernel install --user --name myproject --display-name "Python 3.11.7 (myproject)"。注意--user参数必须加，否则内核注册到系统级，普通用户无权限。
误区三：忽略内核启动日志
点击“Run All”没反应？按Ctrl+Shift+P，输入“Jupyter: Show Log”，看最后几行。如果出现ModuleNotFoundError: No module named 'matplotlib'，说明内核环境缺包；如果卡在Starting kernel...，大概率是ipykernel版本和Python不兼容——比如Python 3.11.7要配ipykernel 6.25+，低版本会无限等待。

验证内核是否正常，新建一个.ipynb文件，第一行写import sys; sys.version，运行后输出必须是3.11.7，且sys.executable路径指向.venv\Scripts\python.exe。

3.6 VS Code设置：十个影响开发效率的隐藏参数

VS Code的settings.json里，以下十项是Python开发的隐形加速器：

"python.defaultInterpreterPath": "./.venv/scripts/python.exe"：强制指定venv路径，避免VS Code自动扫描出错
"python.formatting.provider": "ruff"：格式化交给Ruff，比autopep8快3倍
"python.linting.enabled": true：开启实时检查，配合Ruff规则
"python.testing.pytestArgs": ["--tb=short"]：测试时只显示简短traceback，减少干扰
"editor.formatOnSave": true：保存自动格式化，和Ruff联动
"files.autoSave": "onFocusChange"：切窗口时自动保存，防丢代码
"python.debugging.justMyCode": true：调试时只停自己代码，跳过库源码
"jupyter.askForKernel": false：关闭内核选择弹窗，用默认内核
"jupyter.textOutputLimit": 100000：提高文本输出上限，避免大数组被截断
"workbench.editor.enablePreview": false：禁用预览模式，每个文件都占独立tab

特别提醒第7项：justMyCode设为true后，调试时按F11进入函数内部，如果函数来自第三方包（如pandas.read_csv），VS Code会直接跳过，不显示库源码。这能极大提升调试专注度——你只关心自己的逻辑，不是去修pandas的bug。

3.7 调试配置：launch.json里被忽略的五个关键字段

VS Code调试Python，很多人直接点绿色三角形，结果报错“Cannot find module”。这是因为VS Code默认用python命令启动，而你的venv可能没激活。必须写launch.json：

{ "version": "0.2.0", "configurations": [ { "name": "Python: Current File", "type": "python", "request": "launch", "module": "pytest", "args": ["${fileBasenameNoExtension}"], "console": "integratedTerminal", "justMyCode": true, "env": {"PYTHONPATH": "${workspaceFolder}"}, "cwd": "${workspaceFolder}", "python": "./.venv/scripts/python.exe" } ] }

关键字段解析：

"python"：显式指定venv里的python.exe，绕过PATH查找
"env"：设置PYTHONPATH，让import能跨目录找模块
"cwd"：设置工作目录，避免相对路径读取文件失败
"console"：用集成终端而非外部终端，方便查看输出
"justMyCode"：再次强调，只调试自己代码

有个反直觉点："module"字段设为"pytest"时，"args"里的${fileBasenameNoExtension}会传给pytest当测试文件名，而不是当脚本参数。如果你想调试普通脚本，删掉"module"，加"program": "${file}"。

4. 实操全流程：从新建项目到交互式调试的十二步现场记录

4.1 第一步：创建项目骨架（2分钟）

打开终端，cd到工作目录，执行：

mkdir mydataanalysis && cd mydataanalysis echo "# My Data Analysis Project" > README.md git init

这步看似简单，但决定了后续所有配置的根路径。VS Code的Python扩展会把项目根目录（含.git或README.md的目录）当作工作区，所有venv、ruff.toml、launch.json都以此为基准。

4.2 第二步：安装Python并验证（3分钟）

从python.org下载Python 3.11.7 Windows installer，安装时勾选“Add Python to PATH”，路径选C:\py311。安装完运行：

python --version # 应输出 Python 3.11.7 where python # 应输出 C:\py311\python.exe

如果where命令返回多个路径，说明PATH里有其他Python，用set PATH=C:\py311;%PATH%临时覆盖，或永久删除冲突路径。

4.3 第三步：安装pyenv-win并设全局版本（2分钟）

PowerShell管理员模式运行安装脚本，然后：

pyenv install 3.11.7 pyenv global 3.11.7 pyenv version # 应输出 3.11.7

此时python --version应仍为3.11.7，证明pyenv接管成功。

4.4 第四步：创建venv并初始化（1分钟）

python -m venv .venv

注意：不要用virtualenv .venv，原生venv更稳定。创建后，VS Code右下角应自动显示“Python 3.11.7 (.\venv)”，如果没有，按Ctrl+Shift+P，输入“Python: Select Interpreter”，手动选.venv\Scripts\python.exe。

4.5 第五步：安装核心包（3分钟）

在VS Code集成终端里（确保右下角显示venv），运行：

pip install --upgrade pip pip install numpy pandas matplotlib scikit-learn pip install jupyter ipykernel pytest pip install ruff

关键点：--upgrade pip必须最先执行，否则旧pip可能不支持pyproject.toml。安装完检查.venv\Lib\site-packages目录，应有numpy-1.26.0.dist-info这类文件夹，证明包装进venv了。

4.6 第六步：配置Ruff（2分钟）

在项目根目录新建ruff.toml，粘贴以下内容：

src = ["."] line-length = 88 select = ["E", "F", "I", "B", "ANN", "SIM", "PERF"] ignore = ["E501", "ANN201"] [tool.ruff.per-file-ignores] "__init__.py" = ["F401"] [tool.ruff.mccabe] max-complexity = 10

保存后，新建test.py，写def hello(): return "world"，Ruff应立刻标出ANN201（缺少类型注解）和SIM102（嵌套if可扁平化）。这证明Ruff已生效。

4.7 第七步：注册Jupyter内核（1分钟）

在集成终端里（venv已激活），运行：

python -m ipykernel install --user --name mydataanalysis --display-name "Python 3.11.7 (mydataanalysis)"

注意--user参数——这是VS Code能识别内核的关键。运行后，~\.jupyter\kernels\mydataanalysis\kernel.json应存在，且argv字段指向.venv\Scripts\python.exe。

4.8 第八步：创建第一个Notebook（1分钟）

在VS Code里，Ctrl+Shift+P → “Jupyter: Create New Blank Notebook”，保存为analysis.ipynb。点击右上角内核选择器，选“Python 3.11.7 (mydataanalysis)”。第一行写：

import sys sys.executable

运行（Ctrl+Enter），输出应为C:\path\to\mydataanalysis\.venv\Scripts\python.exe，证明内核指向venv。

4.9 第九步：写一个可调试的脚本（2分钟）

新建main.py：

def calculate_mean(numbers): """Calculate mean of numbers list.""" return sum(numbers) / len(numbers) if __name__ == "__main__": data = [1, 2, 3, 4, 5] result = calculate_mean(data) print(f"Mean: {result}")

按F5启动调试，断点打在result = calculate_mean(data)行，调试器应停住，变量查看器显示data = [1, 2, 3, 4, 5]，证明调试环境正常。

4.10 第十步：配置launch.json（1分钟）

按Ctrl+Shift+P → “Debug: Open launch.json”，选“Python File”，替换为：

{ "version": "0.2.0", "configurations": [ { "name": "Python: Current File", "type": "python", "request": "launch", "module": "pytest", "args": ["${fileBasenameNoExtension}"], "console": "integratedTerminal", "justMyCode": true, "env": {"PYTHONPATH": "${workspaceFolder}"}, "cwd": "${workspaceFolder}", "python": "./.venv/scripts/python.exe" } ] }

保存后，F5调试main.py，应正常输出。

4.11 第十一步：用Interactive Window做探索式分析（3分钟）

新建explore.py，写：

import pandas as pd import numpy as np # 生成示例数据 df = pd.DataFrame({ 'x': np.random.randn(100), 'y': np.random.randn(100) }) # 计算相关系数 corr = df['x'].corr(df['y']) print(f"Correlation: {corr:.3f}") # 绘图 df.plot.scatter('x', 'y')

选中全部代码，按Ctrl+Enter（不是F5），代码会在Interactive Window里逐块执行。df.plot.scatter()会直接在VS Code里弹出图形窗口，而不是打印文本——这就是Interactive Window的核心价值：像Notebook一样交互，但无缝集成在代码编辑器里。

4.12 第十二步：提交配置到Git（1分钟）

新建.gitignore，加入：

.venv/ __pycache__/ *.pyc *.pyo *.pyd .Python pip-log.txt .ipynb_checkpoints

然后：

git add . git commit -m "chore: init python dev environment with venv, ruff, jupyter"

这样团队新人clone后，只需python -m venv .venv && pip install -r requirements.txt，环境就完全一致。

5. 常见问题排查：十五个真实故障场景与解决路径

5.1 故障现象：VS Code右下角显示“Python 3.11.7”，但点开是灰色，无法选择解释器

原因：VS Code的Python扩展缓存了旧的解释器列表，或pyenv-win的版本未被识别。
解决：

按Ctrl+Shift+P → “Python: Clear Cache and Reload Window”
关闭VS Code，删除%USERPROFILE%\AppData\Roaming\Code\User\globalStorage\ms-python.python目录
重启VS Code，再执行“Python: Select Interpreter”

提示：如果pyenv-win安装后VS Code仍不识别，检查$HOME\.pyenv\pyenv-win\pyenv-win\pyenv.ps1是否被PowerShell策略阻止。运行Get-ExecutionPolicy，若为Restricted，执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser。

5.2 故障现象：Ruff检查不生效，代码写错也不标红

原因：Ruff插件未启用，或ruff.toml路径不对，或VS Code没重启。
解决：

按Ctrl+Shift+P → “Developer: Toggle Developer Tools”，看Console是否有Ruff: failed to spawn错误
确认ruff.toml在项目根目录（和README.md同级）
在集成终端运行ruff --version，若报错“command not found”，说明pip install没在venv里执行

5.3 故障现象：Jupyter Interactive Window点击“Run All”后一直转圈，无输出

原因：内核启动超时，通常因ipykernel版本与Python不兼容。
解决：

在venv里运行pip list | findstr ipykernel，确认版本≥6.25
若版本低，pip install --upgrade ipykernel
按Ctrl+Shift+P → “Jupyter: Show Log”，看最后一行是否有OSError: [WinError 10013]——这是Windows防火墙阻止，临时关闭防火墙测试

5.4 故障现象：调试时断点不触发，程序直接跑完

原因：launch.json里"python"字段指向错误路径，或"justMyCode"设为false导致跳过。
解决：

检查"python"值是否为./.venv/scripts/python.exe（Windows用反斜杠）
确认"justMyCode"为true
在main.py第一行加import pdb; pdb.set_trace()，看是否进入调试器

5.5 故障现象：import pandas报错“No module named 'pandas'”，但pip list显示已安装

原因：VS Code的终端和调试器用的不是同一个Python解释器。
解决：

在集成终端运行which python（Linux/Mac）或where python（Windows），确认路径
对比launch.json里的"python"路径，必须完全一致
如果不一致，在终端里执行code .重新打开VS Code，确保继承终端环境

5.6 故障现象：Ruff报“ANN101 Missing type annotation for function argument”，但函数是私有方法

原因：Ruff默认检查所有函数，包括以_开头的私有方法。
解决：在ruff.toml里加：

[tool.ruff.per-file-ignores] "*_test.py" = ["ANN"] "*.py" = ["ANN101", "ANN102"]

这样私有函数和测试文件都不检查类型注解。

5.7 故障现象：Jupyter绘图不显示，只输出`<Figure size ...>`文本

原因：matplotlib后端未设为inline。
解决：在Notebook第一行加：

%matplotlib inline

或在ruff.toml同级建matplotlibrc文件，写backend: agg。

5.8 故障现象：pyenv install失败，报“SSL certificate problem”

原因：Windows证书存储不更新，pyenv下载时验证失败。
解决：

下载最新cacert.pem（https://curl.se/ca/cacert.pem）
设置环境变量：$env:SSL_CERT_FILE="C:\path\to\cacert.pem"
重启PowerShell再试

5.9 故障现象：VS Code启动慢，Python扩展加载卡住

原因：Python扩展扫描了整个磁盘找解释器。
解决：在settings.json里加：

"python.defaultInterpreterPath": "./.venv/scripts/python.exe", "python.explainInstall": false, "python.languageServer": "Pylance"

禁用自动解释器发现，强制指定路径。

5.10 故障现象：Interactive Window里plt.show()弹出独立窗口，而非内嵌

原因：matplotlib后端设为Qt5Agg等GUI后端。
解决：在代码开头加：

import matplotlib matplotlib.use('Agg') # 强制用非GUI后端 import matplotlib.pyplot as plt

5.11 故障现象：pyenv global设置后，cmd里python --version仍是旧版本

原因：pyenv-win的PowerShell配置未加载。
解决：编辑$PROFILE，加：

Invoke-Expression (&"C:\Users\用户名\.pyenv\pyenv-win\pyenv.ps1" --init | Out-String)

然后重启PowerShell。

5.12 故障现象：Ruff格式化后，代码缩进变4空格，但团队用2空格

原因：Ruff默认用4空格，需显式配置。
解决：在ruff.toml里加：

[tool.ruff.format] indent-style = "space" indent-width = 2

5.13 故障现象：Jupyter单元格执行后，变量查看器不显示DataFrame

原因：VS Code的Jupyter扩展变量查看器只支持基础类型，默认不展开DataFrame。
解决：在设置里搜“jupyter.variableView”，勾选“Enable Variable View for DataFrames”。

5.14 故障现象：venv创建后，Scripts目录里没有activate.bat

原因：Windows Defender实时保护误删了脚本文件。
解决：

临时关闭Defender实时保护
python -m venv .venv重试
重新启用Defender

5.15 故障现象：pyenv install 3.11.7卡在“Downloading...”，进度条不动

原因：GitHub release下载被限速。
解决：

手动下载https://www.python.org/ftp/python/3.11.7/python-3.11.7-amd64.exe
放到$HOME\.pyenv\pyenv-win\cache\目录
再运行pyenv install 3.11.7，pyenv会优先用本地缓存

6. 实操心得：五年踩过的七个深坑与三个黄金法则

6.1 七个深坑：那些没人告诉你的“理所当然”

坑一：Windows路径分隔符混用导致venv失效
我曾把"python.defaultInterpreterPath"设为".venv\Scripts\python.exe"（反斜杠），结果VS Code报错。后来发现VS Code内部用Node.js，路径处理用正斜杠，必须写成"./.venv/Scripts/python.exe"。这个细节在文档里根本没提，全靠debug时看VS Code的开发者工具Network面板抓请求URL才发现。

坑二：Ruff的--fix参数会破坏类型注解
有次用ruff --fix批量修复代码，结果把def func(x: int) -> str:改成def func(x) -> str:，删掉了参数类型。后来查Ruff源码，发现--fix默认不处理ANN规则，必须加--select ANN才生效。现在我的习惯是：先ruff check --select ANN看类型问题，再手动修复，绝不--fix。

坑三：Jupyter内核注册后，VS Code仍用旧内核
ipykernel install后，VS Code的内核列表没刷新。必须按Ctrl+Shift+P → “Jupyter: Refresh Kernel List”，否则选的还是旧的。这个命令在菜单里根本找不到，全靠社区帖子挖出来。

坑四：pyenv-win的global设置不生效于VS Code的集成终端
因为VS Code启动时读的是Windows注册表的PATH，而pyenv-win改的是PowerShell的$PROFILE。解决方案是：在VS Code设置里加"terminal.integrated.env.windows": {"PYENV_ROOT": "C:\\Users\\用户名\\.pyenv\\pyenv-win"}，让终端继承pyenv环境。

坑五：matplotlib绘图内存泄漏
Interactive Window里反复运行plt.plot()，内存占用飙升。原因是每次plot都创建新Figure，没显式plt.close()。现在我的模板是：

fig, ax = plt.subplots() ax.plot(x, y) plt.show() plt.close(fig) # 必加！

坑六：venv里pip install包后，VS Code的IntelliSense不识别
因为Pylance语言服务器缓存了旧的包信息。解决：按Ctrl+Shift+P → “Python: Restart Language Server”，或者删%USERPROFILE%\AppData\Roaming\Code\User\globalStorage\ms-python.vscode-pylance。

坑七：Ruff检查.pyi存根文件时报错
.pyi文件是类型存根，Ruff默认不检查，但如果你的项目结构里有stubs/目录，Ruff会扫进去。必须在ruff.toml里加extend-exclude = ["stubs/", "*.pyi"]。

6.2 三个黄金法则：让配置一次成型，十年不翻车

法则一：所有路径用相对路径，拒绝绝对路径
"python.defaultInterpreterPath": "./.venv/Scripts/python.exe"比"C:/project/.venv/Scripts/python.exe"强十倍。因为项目可能clone到任何路径，相对路径保证可移植性。VS Code的"${workspaceFolder}"变量也是相对路径思维的延伸。

法则二：配置即代码，所有设置存Git
.vscode/settings.json、ruff.toml、launch.json、.gitignore全部提交。这样新人git clone && code .后，环境自动就绪。我见过太多团队把VS Code设置存在个人电脑里，结果CI构建失败——因为CI服务器没装Ruff插件。

法则三：验证胜于相信，每步操作必看输出
装完Python，必跑where python；创建venv，必看VS Code右下角；装完Ruff，必写一行错代码看是否标红；注册内核，必运行sys.executable确认路径。这些验证动作花30秒，但能避免后面3小时的排查。

最后分享个小技巧：

企业官网建设流程全解析