|
|
@@ -0,0 +1,198 @@
|
|
|
+# 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 项目开发中的基础实践之一。通过合理使用虚拟环境，可以更稳定地管理依赖、减少环境冲突，并提升项目的可维护性和可复现性。
|
