Python 3 虚拟环境 (venv) 极简指南

Python 3 虚拟环境 (venv) 极简指南

这是 Python 3 自带虚拟环境 venv 的使用文档，涵盖从创建、使用到 Git 协作的全流程。

一、 快速开始 (本地开发)

1. 创建虚拟环境

在你的项目根目录下运行：

# 第二个 venv 是虚拟环境文件夹的名字，你可以随意取，但推荐用 venv
python -m venv venv
# 或者 (Mac/Linux 可能需要用 python3)
python3 -m venv venv

2. 激活环境

创建后需要激活才能使用（激活后终端前面会出现 (venv) 标识）：

• Mac / Linux:

  source venv/bin/activate
  

• Windows (CMD / PowerShell):

  .\venv\Scripts\activate
  

3. 安装依赖

激活状态下，使用 pip 安装包，它们只会安装在这个虚拟环境中，不污染全局：

pip install requests

4. 退出环境

deactivate

---

二、 Git 协作流程 (核心)

注意： 虚拟环境文件夹（venv/）绝对不要提交到 Git，体积大且跨平台不兼容。我们只提交依赖列表。

1. 提交代码前 (开发者 A)

在提交代码前，必须生成依赖清单文件 requirements.txt：

# 确保已激活虚拟环境
pip freeze > requirements.txt

重要：配置 .gitignore 在项目根目录新建或编辑 .gitignore 文件，添加以下内容：

venv/
__pycache__/
*.pyc

2. 拉取项目后 (开发者 B 或 重新部署)

当你 git clone 或 git pull 一个新项目下来时，venv 文件夹是不存在的。你需要重建环境：

1. 拉取代码：

   git pull origin main
   

2. 创建新的虚拟环境 (仅第一次需要)：

   python3 -m venv venv
   

3. 激活环境：

   source venv/bin/activate  # Mac/Linux
   # 或 .\venv\Scripts\activate (Windows)
   

4. 一键安装所有依赖：

   pip install -r requirements.txt
   

5. 运行项目：

   python main.py
   

---

三、 总结口诀

1. 建环境：python -m venv venv
2. 用之前：先激活 (source venv/bin/activate 或 activate)
3. 提交前：导出 pip freeze > requirements.txt
4. 拉取后：安装 pip install -r requirements.txt

---

四、 附录：常用 Python .gitignore 模板

在项目根目录下创建一个名为 .gitignore 的文件，复制以下内容：

# --- Python 通用忽略 ---
# 字节码文件
__pycache__/
*.py[cod]
*$py.class

# C 扩展
*.so

# --- 虚拟环境 ---
# 常见的虚拟环境目录名
venv/
env/
.venv/
.env/
venv*/
ENV/

# --- IDE 配置 (可选，建议忽略) ---
.idea/
.vscode/
*.swp
*.swo

# --- 操作系统文件 ---
# macOS
.DS_Store
.AppleDouble
.LSOverride

# Windows
Thumbs.db
ehthumbs.db
Desktop.ini

# --- 敏感信息 (非常重要!) ---
# 环境变量文件 (通常包含密钥)
.env
.env.local
config.py
secrets.py

# --- 日志和数据库 ---
*.log
*.sqlite
*.db