🐍 Day1 : Python 环境搭建 — 现代 Python 工作流

学习路径：Python_AIGC · Day 1

掌握一套干净、可复现的 Python 开发环境，是一切工程的基础。

1️⃣ 为什么需要环境管理？

Python 版本混乱（2.7 vs 3.x）、项目依赖冲突（A 要 Django3，B 要 Django4）是日常痛点。一个合格的 Python 环境方案要解决三个问题：

问题	解决方案
多版本 Python	pyenv
依赖隔离	venv（内置）
依赖锁定 & 快速安装	uv

2️⃣ pyenv --- Python 版本管理

安装

bash 复制代码

# macOS
brew install pyenv

# 写入 shell 配置
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc

常用命令

bash 复制代码

# 查看可安装版本
pyenv install --list | grep " 3.[0-9]*.[0-9]*$"

# 安装指定版本
pyenv install 3.12.3
pyenv install 3.11.9

# 查看已安装
pyenv versions

# 全局默认版本
pyenv global 3.12.3

# 项目本地版本（项目目录下创建 .python-version）
cd my-project
pyenv local 3.11.9

🔑 核心思路 ：pyenv global 设默认，pyenv local 按项目锁定。

3️⃣ uv --- 下一代包管理器

uv 比 pip 快 10-100 倍，由 Rust 实现，兼容 pip 生态。

安装

bash 复制代码

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或 brew
brew install uv

日常使用

bash 复制代码

# 创建虚拟环境（比 python -m venv 快 50x）
uv venv

# 激活（与 venv 完全一致）
source .venv/bin/activate

# 安装依赖
uv pip install fastapi uvicorn

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

# 锁定依赖版本
uv pip freeze > requirements.txt

uv 独有的优势

bash 复制代码

# 一键创建并进入新项目
uv init my-app
cd my-app

# 添加依赖（自动更新 pyproject.toml）
uv add httpx

# 直接运行脚本（无需激活环境）
uv run python script.py

4️⃣ venv --- Python 内置虚拟环境

即便有 uv，理解 venv 原理仍然重要。

bash 复制代码

# 创建
python -m venv .venv

# 激活（每次新终端都要执行）
source .venv/bin/activate

# 退出
deactivate

# 删除（普通目录，直接删）
rm -rf .venv

💡 原理 ：.venv 里有个 bin/python 软链指向 pyenv 的 Python，bin/ 目录优先在 $PATH 前，所以 python 和 pip 都指向虚拟环境。

5️⃣ pip 加速配置

bash 复制代码

# 阿里云镜像（国内必配）
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/

# 一次性使用
pip install numpy -i https://mirrors.aliyun.com/pypi/simple/

6️⃣ 完整项目脚手架

bash 复制代码

# 一步到位：创建完整项目环境
mkdir my-llm-project && cd my-llm-project
pyenv local 3.12.3
uv venv
source .venv/bin/activate

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

# 验证
python --version   # 3.12.3
which python       # /.venv/bin/python

⚠️ 避坑总结

坑	原因	解法
`pip install` 装到系统 Python	没激活 venv	先 `source .venv/bin/activate`
切换项目后 Python 版本不对	没设 `.python-version`	`pyenv local 3.x.x`
`pip install` 很慢	默认走 pypi.org	配国内镜像
依赖版本冲突	没用 lock 文件	`uv pip freeze > requirements.txt`
`python` 找不到	pyenv 没生效	检查 `.zshrc` 里的 init 命令

📝 今日小结

✅ pyenv 管理 Python 多版本
✅ uv 作为快 100 倍的包管理器
✅ venv 实现依赖隔离
✅ 一套可复现的项目初始化流程