📚 课程目录第2章 Python开发环境搭建

2. Python 开发环境搭建：安装 Python、虚拟环境、包管理工具

说实话，做样本元数据管道开发，环境搭建这步要是没弄好，后面能把你折腾死。我一个同事曾经花了一整天排查依赖冲突，最后发现是系统 Python 和 conda 环境混用了。嗯，今天我把这些年踩过的坑和最佳实践一次性说清楚。

2.1 选哪个 Python 版本？

我个人习惯用 Python 3.10 或 3.11。3.12 也可以，但有些元数据相关的库还没完全跟上。你想想看，管道跑一半报 ModuleNotFoundError，多闹心。

如果你用 conda，推荐 Python 3.11。Anaconda 2024 系列默认就是这个版本，兼容性最好。

2.2 安装 Python —— 别用系统自带的

Windows 用户直接去 python.org 下载安装包。记得勾选 “Add Python to PATH”。我在项目初期没勾这个，结果后面每次敲命令都要跑绝对路径，烦死了。

macOS / Linux 用户，我建议用 pyenv 管理多版本：

# 安装 pyenv
curl https://pyenv.run | bash
# 安装 Python 3.11
pyenv install 3.11.9
pyenv global 3.11.9
# 验证
python --version

千万别直接用 apt install python3 或 brew install python。我曾经在 Ubuntu 上这样干过，结果系统脚本和新装库的 pip 版本冲突，一升级 pip 就把系统包管理器搞挂了……

安装方式	推荐场景	注意点
python.org 安装包	Windows / macOS 单用户	必须勾选「Add to PATH」
pyenv	Linux / macOS 多版本	注意 shell 配置
conda 内置 Python	数据科学团队协作	不要和系统 Python 混用

千万不要用 sudo pip install 装任何包。这会把包写进系统目录，以后想移除都难。

2.3 虚拟环境 —— 每个项目一个“小监狱”

说白了，虚拟环境就是给每个项目隔离 Python 运行时。你在 A 项目用 pandas 1.5，B 项目用 pandas 2.0，互不干扰。我刚开始做管道时没这个概念，一个全局环境里装了 30 多个包，版本乱到不敢更新任何东西。

2.3.1 用 venv（Python 自带）

这是最轻量的方案，你不需要装任何第三方工具：

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

# 激活（Windows）
.venv\Scripts\activate

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

# 退出
deactivate

项目根目录下会出现一个 .venv 文件夹。记得把它加到 .gitignore 里。

我惯用的项目结构：

sample-metadata-pipeline/
├── .venv/          # 虚拟环境
├── src/
├── tests/
├── data/
├── requirements.txt
└── .gitignore

2.3.2 用 conda 环境（适合科学计算）

如果你用了 Anaconda / Miniconda，conda 环境自带更多数据和科学计算库的预编译包：

# 创建环境，指定 Python 版本
conda create -n metadata-pipe python=3.11

# 激活
conda activate metadata-pipe

# 退出
conda deactivate

# 查看所有环境
conda env list

为什么我推荐 conda？因为样本元数据管道经常用到 pandas、numpy、scipy，甚至 RAPIDS（GPU 加速）。conda 能直接帮你解决底层 C 库的依赖 —— 这点 pip 做不到。我在一个项目中用 pip 装 scipy，结果折腾了半小时编译环境。换成 conda，两分钟搞定。

特性	venv	conda env
依赖来源	PyPI（pip）	conda 仓库 + PyPI
非 Python 库	需手动编译	自动处理
环境隔离	仅 Python 包	包含系统级库
跨平台	好	非常好（预编译包）
推荐场景	纯 Python 项目	科学计算 / 数据工程

2.4 包管理工具：pip vs conda

还是那句话：pip 适合纯 Python 包，conda 适合带 C 扩展的包。我通常这么搭配：

日常开发：用 venv + pip
数据管道 / 机器学习：用 conda + pip（先 conda install 装科学计算包，再用 pip 装特色库）

2.4.1 pip 的基本用法

# 安装
pip install pandas numpy

# 固定版本
pip install pandas==2.0.3

# 从 requirements.txt 安装
pip install -r requirements.txt

# 导出当前环境（给同事用）
pip freeze > requirements.txt

我习惯用 pip freeze 加上 --local 参数，这样只导出当前虚拟环境里的包，不会混入系统级包。

2.4.2 conda 的基本用法

# 从指定频道安装
conda install -c conda-forge pandas

# 安装指定版本
conda install numpy=1.26.0

# 导出环境文件
conda env export > environment.yml

# 通过环境文件还原
conda env create -f environment.yml

你可能会问：先装 conda 还是先装 pip？不要混着装。我见过有人先 conda install 了 pandas，又 pip install pandas——结果装了两份，版本还不同，代码里 import pandas 到底用哪个版本全看 sys.path 顺序，极其坑人。

2.4.3 一个稳妥的安装顺序

# 第一步：创建 conda 环境
conda create -n meta-pipe python=3.11

# 第二步：激活
conda activate meta-pipe

# 第三步：用 conda 安装主流科学计算包
conda install pandas numpy matplotlib scikit-learn

# 第四步：用 pip 安装次要包
pip install pymongo openpyxl

# 这样 conda 先占住大库的 C 依赖，pip 只装纯 Python 包

如果在 conda 环境中用了 pip install 装了某个包，再执行 conda install 可能会破坏 pip 安装的包。记住：conda 优先，pip 放后面，别反过来。

2.5 开发环境全貌：一张图说清楚

下面这张 SVG 展示了我们搭建的开发环境组件以及它们之间的关系。

2.6 我常用的环境管理技巧

项目根目录放 requirements.txt，README 里写明激活虚拟环境后 pip install -r requirements.txt 一步到位。
用 pip-tools 编译精确版本：pip-compile 生成 requirements.txt，pip-sync 同步环境。这样团队不会出现“在我机器上能跑”的梗。
conda 环境别太大：每个 pipeline 单独一个环境，依赖控制在 30 个以内。我见过一个同事一个环境装了 200 多个包，遇到升级直接崩。
记着 .gitignore 里排除环境目录：.venv/、envs/、__pycache__/。

一句话总结：用 pyenv 管理 Python 版本，用 venv 或 conda 隔离项目环境，用 pip 或 conda 按需安装包，用 requirements.txt 或 environment.yml 锁定版本。别把工具混着用，也别把环境装到系统里。

好了，环境搭好，后面就可以真正开始写管道逻辑了。你先按上面的步骤把环境跑通，有问题随时回去看这张图。