# Python 虚拟环境说明

本文档介绍如何在 Python 项目中创建、激活、管理和清理虚拟环境，以确保每个项目都拥有独立、可复现的依赖环境。

## 目录

- [为什么需要虚拟环境](#为什么需要虚拟环境)
- [创建虚拟环境](#创建虚拟环境)
- [激活虚拟环境](#激活虚拟环境)
- [检查环境状态](#检查环境状态)
- [安装依赖包](#安装依赖包)
- [退出虚拟环境](#退出虚拟环境)
- [删除虚拟环境](#删除虚拟环境)
- [常见问题](#常见问题)
- [最佳实践](#最佳实践)
- [命令速查](#命令速查)

## 为什么需要虚拟环境

虚拟环境可以让每个 Python 项目拥有独立的解释器和第三方库环境，带来以下好处：

- 避免不同项目之间的依赖冲突
- 防止全局 Python 环境被污染
- 便于在开发、测试和部署中保持一致
- 方便在不同 Python 版本之间切换

## 创建虚拟环境

在项目根目录中执行以下命令：

### Windows
```bash
python -m venv .venv
```

### macOS / Linux
```bash
python3 -m venv .venv
```

如果系统中安装了多个 Python 版本，可以指定版本：

### Windows
```bash
py -3.11 -m venv .venv
```

### macOS / Linux
```bash
python3.11 -m venv .venv
```

执行完成后，当前目录会生成一个 `.venv` 目录，用于保存该虚拟环境的文件。

## 激活虚拟环境

### Windows (Command Prompt)
```bash
.venv\Scripts\activate
```

### Windows (PowerShell)
```powershell
.\.venv\Scripts\Activate.ps1
```

### macOS / Linux
```bash
source .venv/bin/activate
```

成功激活后，命令提示符通常会显示环境名称，例如：

```bash
(.venv) C:\project\>
```

## 检查环境状态

在虚拟环境中，可以验证当前 Python 和 pip 是否来自当前环境：

```bash
python --version
pip --version
```

也可以查看当前解释器位置：

```bash
which python
```

在 Windows PowerShell 中：

```powershell
Get-Command python
```

## 安装依赖包

在激活虚拟环境之后，安装项目依赖：

```bash
pip install requests
```

如果项目中已有依赖清单：

```bash
pip install -r requirements.txt
```

如果需要导出当前环境中的依赖：

```bash
pip freeze > requirements.txt
```

## 退出虚拟环境

开发完成后，可以退出虚拟环境：

```bash
deactivate
```

## 删除虚拟环境

如果不再需要该环境，可以直接删除虚拟环境目录：

### Windows
```bash
rmdir /s /q .venv
```

### macOS / Linux
```bash
rm -rf .venv
```

## 常见问题

### 1. `python` 命令找不到

通常是因为没有将 Python 添加到系统 PATH。可以检查安装后的 Python 路径，或使用 `py`（Windows）或 `python3`（macOS / Linux）。

### 2. PowerShell 无法激活脚本

如果遇到脚本执行策略限制，可以在 PowerShell 中执行：

```powershell
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
```

然后再次尝试激活虚拟环境。

### 3. 依赖包安装失败

可以先升级 pip：

```bash
python -m pip install --upgrade pip
```

然后重新安装依赖。

## 最佳实践

- 每个项目使用独立的虚拟环境
- 将依赖写入 `requirements.txt`，便于复现和部署
- 不要将 `.venv` 目录提交到版本控制系统中
- 在团队协作中，建议通过 `requirements.txt` 或 `pyproject.toml` 统一环境配置

## 命令速查

```bash
# 创建虚拟环境
python -m venv .venv

# Windows 激活
.venv\Scripts\activate

# PowerShell 激活
.\.venv\Scripts\Activate.ps1

# macOS / Linux 激活
source .venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 退出虚拟环境
deactivate
```

## 结论

Python 虚拟环境是 Python 项目开发中的基础实践之一。通过合理使用虚拟环境，可以更稳定地管理依赖、减少环境冲突，并提升项目的可维护性和可复现性。