如何在VSCode中管理Python项目的requirements.txt文件

用过VSCode做Python开发的，十有八九都踩过同一个坑：在终端里pip install -r requirements.txt跑得稳稳当当，可一运行代码就报ModuleNotFoundError。明明装了包，怎么就找不到？

先说最核心的原因——不是命令敲错了，而是你终端里用的Python解释器，和VSCode调试、运行时用的根本不是同一个。你看着右下角状态栏写着/usr/bin/python3或某个.venv，可终端里却偷偷调用了另一个环境。两路兵马，各走各的，包自然装不到该去的地方。

VSCode里pip install -r requirements.txt不生效，根本原因是什么

要解决这个问题，其实就几个步骤，但每一步都得确认到位。

• 先按Ctrl+Shift+P（Win/Linux）或Cmd+Shift+P（macOS），输入Python: Select Interpreter，选中项目根目录下的.venv/bin/python（macOS/Linux）或.venv\Scripts\python.exe（Windows）。注意路径要跟项目里的虚拟环境一致。
• 再瞅一眼右下角状态栏，显示的路径和刚才选的是否一样。不一样的话，点它手动切换过去。
• 打开集成终端（Ctrl+`），执行which python（macOS/Linux）或where python（Windows）。输出结果必须和状态栏路径完全一致，一个字都不能差。
• 如果终端里python -m pip list看不到你刚装的包，说明pip install装到了别的环境里。这时候只有一个办法：用python -m pip install -r requirements.txt，强制调用当前解释器自带的pip来安装。

生成requirements.txt时，pip freeze为什么不能直接用

很多人习惯用pip freeze > requirements.txt，结果生成的列表里堆满了pip、setuptools、wheel，甚至连pylint、black这类开发依赖都倒进去了。到了部署环境，一堆无用甚至冲突的包跟着装上，轻则浪费空间，重则直接报错。

推荐的做法要看场景：

• 生产项目优先用pipreqs：先装pip install pipreqs，再在项目根目录运行pipreqs . --force。它只扫描代码里的import语句，生成最小依赖集，清爽很多。
• 如果项目已经有setup.py或pyproject.toml，用pip-tools更稳妥：pip install pip-tools，写好requirements.in（只写顶层依赖，比如requests、numpy），再运行pip-compile requirements.in。它会自动解析并锁定所有子依赖。
• 生成后记得检查版本号格式：带==的是精确锁定版（如requests==2.31.0），适合CI/CD；不带版本（如requests）会导致每次构建都拉最新版，容易蹦出breaking change，慎用。

requirements.txt里写版本号，该用==、>=还是~=

版本符号选不对，轻则CI失败，重则线上崩给你看。

• ==：精确锁定，最适合生产环境。缺点是升级得手动改。例如django==4.2.12，谁也别想动。
• >=：允许小版本和补丁升级，但可能意外升到不兼容的大版本。比如requests>=2.28.0，万一哪天出了3.0.0并且不向后兼容，那就惨了。
• ~=：推荐用于多数依赖，意思是“兼容性升级”。等价于>=X.Y.Z, ==X.*。例如click~=8.1.0，允许8.1.x内的任何补丁版本，但不会升到8.2.0或9.0.0，安全得多。
• 注意格式：别在符号和版本之间加空格，比如requests ~= 2.31.0在某些旧版pip里会解析失败。写成requests~=2.31.0最保险。

VSCode里右键“从requirements.txt安装”为啥有时没反应

这个右键功能看起来很贴心，但实际使用中经常失灵。它只在VSCode成功识别出Python环境节点时才可用，而且依赖底层扩展对项目结构的解析。很多时候，它要么找不到requirements.txt，要么环境节点根本没加载出来。

几个排查方向：

• 确认项目根目录下有requirements.txt，且文件名全小写、无空格、无隐藏字符。
• 关闭当前文件夹，重新打开（不是关闭窗口再打开，而是从菜单里重新打开文件夹），让Python扩展重新扫描环境。
• 如果资源管理器里的Python Environment节点根本不显示，说明VSCode没检测到解释器——先走一遍Python: Select Interpreter流程。
• 最稳妥的办法：老老实实在集成终端里手动跑python -m pip install -r requirements.txt，比右键菜单稳定一百倍。

实际项目里最容易被忽略的，其实是.vscode/settings.json里没配置"python.defaultInterpreterPath"。一旦你换电脑、重装VSCode，或者把项目分享给同事，这个配置一丢，所有环境隔离就形同虚设了——它不像requirements.txt那样会被git提交，你得手动补上才能保证团队一致。