第2章：环境准备 — Python版本管理、虚拟环境与依赖管理
说实话，很多初学者甚至一些有经验的开发者，都栽在环境配置上。
我记得刚入行那会儿，最怕听到的一句话就是：「在我机器上明明是好的啊！」。后来我才明白，项目骨架的第一步，不是写代码，而是把开发环境管好。说白了，就是管好三件事：Python版本、虚拟环境、依赖管理。
2.1 Python版本管理 — 用pyenv告别版本混乱
你有没有遇到过这种情况？系统自带的Python是2.7，项目A需要3.8，项目B需要3.10。硬装的话，迟早会出问题。
我个人习惯用pyenv来解决这个问题。它不会动系统的Python，而是让你在用户目录下自由切换版本。
安装pyenv
在macOS或Linux上，一行命令搞定：
curl https://pyenv.run | bash然后配置一下shell环境变量：
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
source ~/.bashrc常用命令一览
| 命令 | 作用 |
|---|---|
pyenv install --list |
查看可安装的Python版本 |
pyenv install 3.10.12 |
安装指定版本 |
pyenv versions |
列出已安装的所有版本 |
pyenv global 3.10.12 |
设置全局默认版本 |
pyenv local 3.8.18 |
在当前目录设置局部版本 |
pyenv local 3.10.12 后，会自动生成一个 .python-version 文件。团队其他人拉取代码后，pyenv会自动切换到对应版本。这个细节，我在好几个团队里都推广过，效果很好。
2.2 虚拟环境 — 让每个项目有自己的小天地
Python版本统一了，但依赖包还是会打架。项目A用Django 3.2，项目B用Django 4.2，装在一起就乱套了。
虚拟环境就是给每个项目一个独立的「包空间」。我最早用virtualenv，后来官方出了venv，再后来有了pipenv。嗯，这里我重点说两种。
2.2.1 原生venv — 轻量、可靠
Python 3.3+ 自带，不需要额外安装：
# 创建虚拟环境
python -m venv .venv
# 激活（Linux/macOS）
source .venv/bin/activate
# 激活（Windows）
.venv\Scripts\activate
# 退出
deactivate激活后，终端前面会出现 (.venv) 提示符。这时候你装的所有包，都只在这个项目里生效。
.venv/ 加到 .gitignore 里。虚拟环境不要提交到代码仓库，否则你会被队友吐槽的。
2.2.2 pipenv — 更现代化的选择
如果你觉得手动激活/退出虚拟环境太麻烦，可以试试pipenv。它把虚拟环境和依赖管理合二为一。
# 安装pipenv
pip install pipenv
# 初始化项目（会自动创建虚拟环境）
pipenv install
# 安装依赖
pipenv install requests
# 进入虚拟环境shell
pipenv shell
# 运行脚本（不用手动激活）
pipenv run python app.pypipenv会自动生成Pipfile和Pipfile.lock。前者记录依赖的「宽松版本」，后者锁定精确版本。这个设计很聪明，我特别喜欢。
Pipfile.lock冲突搞得团队焦头烂额。后来我们约定：只有主分支才能更新lock文件，开发分支只改Pipfile。嗯，规矩定好，问题就少了一半。
2.3 依赖管理 — 从requirements.txt到poetry
依赖管理，说白了就是回答两个问题：项目需要哪些包？这些包需要什么版本？
2.3.1 传统方式：requirements.txt
这是最经典的做法，简单直接：
# 生成当前环境的依赖列表
pip freeze > requirements.txt
# 在另一台机器上安装
pip install -r requirements.txt但有个坑：pip freeze会把所有已安装的包都列出来，包括那些间接依赖。你想想看，如果A包依赖B包，B包又依赖C包，那requirements.txt里会有一大串。维护起来很痛苦。
2.3.2 现代方案：Poetry
我个人现在最推荐的是Poetry。它解决了上面所有痛点。
# 安装Poetry
curl -sSL https://install.python-poetry.org | python3 -
# 初始化项目
poetry init
# 添加依赖
poetry add flask
# 添加开发依赖
poetry add --dev pytest
# 安装所有依赖
poetry install
# 导出requirements.txt（给CI/CD用）
poetry export -f requirements.txt --output requirements.txtPoetry用pyproject.toml来管理项目元数据和依赖，用poetry.lock锁定版本。结构清晰，可读性强。
# pyproject.toml 示例
[tool.poetry]
name = "my-project"
version = "0.1.0"
description = "从零构建项目骨架"
authors = ["Your Name "]
[tool.poetry.dependencies]
python = "^3.10"
flask = "^2.3"
requests = "^2.31"
[tool.poetry.dev-dependencies]
pytest = "^7.4"
black = "^23.7"
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api poetry.lock能保证每个人安装的依赖版本完全一致。有一次线上出了个bug，排查半天发现是某个人本地装了个新版本的库。从那以后，lock文件就成了我们团队的「圣旨」。
2.4 三者的配合使用
你可能会问：这三个工具到底怎么配合？我画个流程图你就明白了。
2.5 我的最终推荐
说了这么多，到底选哪个？我直接给结论：
- 个人小项目：venv + pip + requirements.txt。够用，简单。
- 团队协作项目：pyenv + poetry。规范，省心。
- 如果你追求极致体验：pyenv + poetry + 配合IDE的虚拟环境自动识别。我目前就是这么用的，基本不用手动操作。