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

1. 这不是“装个插件就完事”的配置而是Python开发环境的底层重建你搜过“VS Code配置Python”点开前十个结果大概率看到的是打开扩展市场→搜Python→点安装→CtrlShiftP→选Python Interpreter→选个路径→搞定。我试过这种流程也教过不下二十个刚转行的朋友照着做结果呢三天后有人来问“为什么import pandas报错”“为什么Jupyter单元格点了没反应”“为什么调试时断点根本不停”——问题全出在那“一步到位”的幻觉里。真实情况是VS Code本身不带Python能力它只是一个高度可定制的编辑器壳子Python解释器、包管理器、格式化工具、静态检查器、Jupyter内核、调试器……这些全是你手动拼装的零件。它们之间不是简单“能用就行”而是存在版本兼容链、路径解析逻辑、进程通信协议、环境隔离机制等一整套隐性规则。比如Ruff要求Python 3.8才能启用全部规则但你系统里默认的python命令可能指向3.7Jupyter 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绝对路径避免虚拟环境激活后还调用到全局Pythonpip 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不是替代flake8blackisort的“更快版本”它是用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而用原生venvvirtualenv是第三方包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再installpip会把包装到激活后的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”没反应按CtrlShiftP输入“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: [--tbshort]测试时只显示简短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_csvVS 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 PATHC:\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)”如果没有按CtrlShiftP输入“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 第六步配置Ruff2分钟在项目根目录新建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 worldRuff应立刻标出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 第八步创建第一个Notebook1分钟在VS Code里CtrlShiftP → “Jupyter: Create New Blank Notebook”保存为analysis.ipynb。点击右上角内核选择器选“Python 3.11.7 (mydataanalysis)”。第一行写import sys sys.executable运行CtrlEnter输出应为C:\path\to\mydataanalysis\.venv\Scripts\python.exe证明内核指向venv。4.9 第九步写一个可调试的脚本2分钟新建main.pydef 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(fMean: {result})按F5启动调试断点打在result calculate_mean(data)行调试器应停住变量查看器显示data [1, 2, 3, 4, 5]证明调试环境正常。4.10 第十步配置launch.json1分钟按CtrlShiftP → “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(fCorrelation: {corr:.3f}) # 绘图 df.plot.scatter(x, y)选中全部代码按CtrlEnter不是F5代码会在Interactive Window里逐块执行。df.plot.scatter()会直接在VS Code里弹出图形窗口而不是打印文本——这就是Interactive Window的核心价值像Notebook一样交互但无缝集成在代码编辑器里。4.12 第十二步提交配置到Git1分钟新建.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的版本未被识别。解决按CtrlShiftP → “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没重启。解决按CtrlShiftP → “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按CtrlShiftP → “Jupyter: Show Log”看最后一行是否有OSError: [WinError 10013]——这是Windows防火墙阻止临时关闭防火墙测试5.4 故障现象调试时断点不触发程序直接跑完原因launch.json里python字段指向错误路径或justMyCode设为false导致跳过。解决检查python值是否为./.venv/scripts/python.exeWindows用反斜杠确认justMyCode为true在main.py第一行加import pdb; pdb.set_trace()看是否进入调试器5.5 故障现象import pandas报错“No module named pandas”但pip list显示已安装原因VS Code的终端和调试器用的不是同一个Python解释器。解决在集成终端运行which pythonLinux/Mac或where pythonWindows确认路径对比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.pemhttps://curl.se/ca/cacert.pem设置环境变量$env:SSL_CERT_FILEC:\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 plt5.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 25.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重试重新启用Defender5.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.7pyenv会优先用本地缓存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的内核列表没刷新。必须按CtrlShiftP → “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语言服务器缓存了旧的包信息。解决按CtrlShiftP → “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小时的排查。最后分享个小技巧