# Python 版本要求

## 必须使用的版本

**Python 3.11.x**

```bash
# 检查 Python 版本
python --version
# 应显示: Python 3.11.x
```

## 为什么不支持其他版本？

| 版本 | 状态 | 原因 |
|------|------|------|
| Python 3.10 | ❌ 不支持 | Panda3D 1.10.16 在 3.10 上有兼容性问题 |
| **Python 3.11** | ✅ **推荐** | 经过完整测试，所有功能正常 |
| Python 3.12 | ⚠️ 未测试 | 可能存在兼容性问题 |
| Python 3.13 | ⚠️ 不推荐 | 当前环境使用，但部分依赖可能有警告 |

## Windows 安装 Python 3.11

### 方法 1: 官网下载

1. 访问: https://www.python.org/downloads/release/python-3119/
2. 下载: `Windows installer (64-bit)`
3. 安装时勾选:
   - ✅ `Add Python to PATH`
   - ✅ `Use admin privileges when installing py.exe`

### 方法 2: 使用 Chocolatey

```powershell
# 安装 Chocolatey 后
choco install python --version=3.11.9
```

### 方法 3: 使用 pyenv-win

```powershell
# 安装 pyenv-win
pip install pyenv-win

# 安装 Python 3.11
pyenv install 3.11.9
pyenv global 3.11.9
```

## 验证安装

```powershell
# 检查版本
python --version
# Python 3.11.9

# 检查 pip
python -m pip --version
# pip 24.x from ...
```

## 安装项目依赖

```powershell
# 创建虚拟环境（推荐）
python -m venv venv
.\venv\Scripts\activate

# 安装依赖
python -m pip install -r requirements/requirements-minimal.txt
```

## 构建要求

构建安装程序时也必须使用 Python 3.11：

```powershell
# 确保使用 Python 3.11
python --version
# Python 3.11.x

# 然后执行构建
.\build_scripts\build_windows.ps1
```

## 常见问题

### Q: 我已经安装了 Python 3.12/3.13，需要卸载吗？
**A**: 不需要卸载，可以同时安装多个版本。使用 `py -3.11` 或指定完整路径调用 Python 3.11。

### Q: 如何切换默认 Python 版本？
**A**: 修改系统 PATH 环境变量，将 Python 3.11 的路径放到其他版本前面。

### Q: 虚拟环境中可以使用不同版本吗？
**A**: 不可以，虚拟环境继承创建它的 Python 版本。需要用 Python 3.11 创建虚拟环境。

---

**最后更新**: 2024年
