🐍 Python 环境管理与虚拟环境全指南

一、核心基础：什么是 Python 解释器？

当你写下一行 print("Hello") 时，电脑看不懂。你需要一个“翻译官”把代码转换成机器指令，这就是 Python 解释器（即你安装的 python.exe）。

虚拟环境是为每个项目建立的独立“样板间”。它在项目文件夹里创建一个 Python 副本（独立的解释器和库目录）。

未开启虚拟环境： pip install 的包全部塞进系统全局目录（如 C:\Users\...\site-packages）。项目文件夹里看不到包，但能跑，因为 Python 会去系统储物间找。
开启虚拟环境： 包会精准安装在项目目录下的 .venv/lib/site-packages 文件夹里。这是专业开发的标准做法。

PyCharm： 非常“强势”。新建项目时会强迫你选择/创建解释器，通过图形化界面帮你完成 创建 -> 激活 -> 绑定。
Cursor： 更加“智能灵活”。它不会强迫你，但会智能检测。当你项目里有了虚拟环境，它会弹窗问你是否切换。点击 Yes 后，配置会记录在 .vscode/settings.json 中。

当你从 GitHub 下载项目时，git clone 只下载代码，不包含依赖包。请务必遵循以下流程，防止依赖污染系统盘：

Clone 项目： git clone 下载代码并用 Cursor 打开文件夹。
严禁直接安装： 不要一打开就运行 pip install！
创建并激活虚拟环境： * 在 Cursor Chat 里说：“帮我创建虚拟环境并激活。”
- 此时项目里会出现 .venv 文件夹。
在环境内安装： 激活后（终端提示符前出现 (.venv)），再运行 pip install -r requirements.txt。
- 结果： 所有的包都会被安装到当前项目的 .venv 文件夹内，系统盘依然干净。

以后每开一个新项目，请直接对 Cursor 下达这个“全自动指令”：

“帮我在当前目录下创建 Python 虚拟环境，激活它，创建一个 .gitignore 文件忽略环境文件夹，并安装 requirements.txt 中的依赖（如果有的话）。”

当右下角弹出 "Detected a new virtual environment..." 时，务必点 "Yes"。
如何检查？ 在终端输入 where python (Win) 或 which python (Mac)。如果路径指向你项目里的 .venv，说明大功告成。

不要移动文件夹： 虚拟环境记录的是绝对路径。如果移动了文件夹，环境可能失效。解决方法： 直接删掉 .venv 文件夹，让 Cursor 重新生成一个。
环境变量： 如果终端输入 python 报错，通常是安装 Python 时没勾选 "Add Python to PATH"。
.gitignore 的重要性： 永远不要把虚拟环境文件夹（.venv）上传到 GitHub，别人应该根据你的 requirements.txt 在他们自己电脑上生成环境。

总结： 源代码是“灵魂”，虚拟环境是“躯干”，依赖包是“工具”。先建环境，再装包，让每个项目成为独立的“自给自足小岛”。

如果你使用 PyCharm 手动创建项目，请务必按照以下“三步走”原则进行配置，以确保依赖包安装在项目内而非系统盘中：

环境选择“生成新的” (New)：
- 在添加解释器界面，务必勾选 “生成新的” (New)，而不是“选择现有”。
- 类型选择： 优先选择 Virtualenv，这是最通用且轻量的隔离方案。
明确“位置” (Location)：
- 确保路径末尾指向你当前项目文件夹下的 .venv 或 venv 目录（例如：E:\YourProject\.venv）。
- 意义： 这一步决定了你的依赖包会“入驻”项目文件夹，实现真正的项目隔离。
确定“基础 Python” (Base Interpreter)：
- 选择你电脑里已有的稳定版 Python（如 Anaconda 里的 python.exe）。
- 避坑指南： 基础 Python 这一列通常提供各种版本的下载选项，除非项目明确要求特定版本，否则不建议点击下载。频繁下载不同版本的 Python 会导致电脑环境路径极度混乱，增加管理负担。

配置成功的标志：

点击确定后，项目左侧目录树会出现一个 .venv 文件夹。
打开 PyCharm 底部终端 (Terminal)，路径前缀显示 (.venv) 字样，此时运行 pip install 的所有包都会精准存放在该文件夹内。