# Pyenv 使用完整指南

Pyenv 是一个强大的 Python 版本管理工具，可以让你轻松安装、切换和管理多个 Python 版本。以下是详细使用指南：

## 1. 安装 Pyenv

### Linux/macOS 安装

```bash
curl https://pyenv.run | bash
```

安装完成后，将以下内容添加到 shell 配置文件（如 `~/.bashrc`, `~/.zshrc` 或 `~/.bash_profile`）：

```bash
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"  # 如果要用虚拟环境插件
```

然后重新加载 shell：

```bash
exec "$SHELL"
```

### Windows 安装

Windows 用户可以使用 [pyenv-win](https://github.com/pyenv-win/pyenv-win)：

```powershell
Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1"
```

## 2. 基本命令

### 安装 Python 版本

```bash
# 查看可安装版本
pyenv install --list

# 安装特定版本
pyenv install 3.9.7

# 安装最新稳定版
pyenv install $(pyenv latest -k 3)
```

### 查看已安装版本

```bash
pyenv versions
```

带 `*` 的表示当前激活的版本。

### 切换 Python 版本

```bash
# 全局设置（影响整个系统）
pyenv global 3.9.7

# 局部设置（仅当前目录及其子目录）
pyenv local 3.8.12

# shell会话级别设置（仅当前终端）
pyenv shell 3.10.0
```

### 卸载 Python 版本

```bash
pyenv uninstall 3.7.12
```

## 3. 高级功能

### 虚拟环境管理

Pyenv 可以与 `pyenv-virtualenv` 插件配合使用：

```bash
# 创建虚拟环境
pyenv virtualenv 3.9.7 my-project-env

# 激活虚拟环境
pyenv activate my-project-env

# 停用虚拟环境
pyenv deactivate

# 删除虚拟环境
pyenv uninstall my-project-env
```

### 版本优先级

Pyenv 按以下顺序决定使用哪个 Python 版本：

1. `PYENV_VERSION` 环境变量
2. 当前目录的 `.python-version` 文件（由 `pyenv local` 创建）
3. 第一个找到的父目录中的 `.python-version` 文件
4. 全局版本（由 `pyenv global` 设置）

### 自定义构建选项

```bash
# 安装时启用优化
PYTHON_CONFIGURE_OPTS="--enable-optimizations" pyenv install 3.9.7

# 安装特定架构版本
env PYTHON_CONFIGURE_OPTS="--enable-shared" pyenv install 3.10.0
```

## 4. 常见问题解决

### 安装失败（缺少依赖）

```bash
# Ubuntu/Debian
sudo apt-get install -y make build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

# CentOS/RHEL
sudo yum install -y gcc zlib-devel bzip2 bzip2-devel readline-devel \
sqlite sqlite-devel openssl-devel tk-devel libffi-devel
```

### 速度慢的解决方法

使用国内镜像：

```bash
# 临时使用镜像
v=3.9.7;wget https://npm.taobao.org/mirrors/python/$v/Python-$v.tar.xz -P ~/.pyenv/cache/;pyenv install $v

# 或设置环境变量
export PYTHON_BUILD_MIRROR_URL="https://npm.taobao.org/mirrors/python"
```

### 更新 Pyenv

```bash
pyenv update
```

## 5. 实际应用示例

### 项目中使用特定 Python 版本

```bash
# 进入项目目录
cd my-project

# 设置项目使用的Python版本
pyenv local 3.8.12

# 创建项目专用虚拟环境
pyenv virtualenv 3.8.12 my-project-env

# 激活环境
pyenv activate my-project-env

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

### 多版本切换演示

```bash
# 查看当前版本
python --version

# 切换到另一个版本
pyenv shell 3.7.12
python --version

# 切换回来
pyenv shell --unset
python --version
```

## 6. 配置建议

在 `~/.pyenv/` 目录下可以配置一些默认行为：

- `plugins/python-build/share/python-build/` - 可以添加自定义的 Python 版本定义
- `cache/` - 缓存下载的 Python 源码包

## 7. 与其他工具集成

### 与 Pipenv 配合使用

```bash
pyenv local 3.9.7
pip install --user pipenv
pipenv install
```

### 与 Poetry 配合使用

```bash
pyenv local 3.10.0
curl -sSL https://install.python-poetry.org | python -
poetry init
```

Pyenv 提供了灵活的 Python 版本管理，特别适合需要同时处理多个项目的开发者。