ljwx-stock/TROUBLESHOOTING_PYTHON.md

Python 环境问题排查

常见问题列表

1. pandas 安装失败（Python 版本问题）
2. LightGBM 编译失败
3. pydantic_settings 模块找不到
4. 依赖安装太慢

---

问题1：pandas 安装失败

症状

error: metadata-generation-failed
× Encountered error while generating package metadata.
╰─> pandas

原因

你的 Python 版本是 3.14.0，太新了！pandas 2.1.3 还不支持 Python 3.14。

解决方案

方案 1：安装 Python 3.12（推荐）

macOS:

# 安装 Python 3.12
brew install [email protected]

# 删除旧的虚拟环境
rm -rf backend/.venv

# 重新启动（脚本会自动检测并使用 python3.12）
./start_app.sh

Linux:

# 安装 Python 3.12
sudo apt update
sudo apt install python3.12 python3.12-venv python3.12-dev

# 删除旧的虚拟环境
rm -rf backend/.venv

# 重新启动
./start_app.sh

方案 2：升级 pandas 版本（实验性）

编辑 backend/requirements.txt，将：

pandas==2.1.3

改为：

pandas>=2.2.0

然后：

rm -rf backend/.venv
./start_app.sh

⚠️ 注意：pandas 2.2+ 可能有 API 变化，需要测试兼容性。

方案 3：手动创建虚拟环境（如果脚本检测失败）

# 使用 Python 3.12 创建虚拟环境
python3.12 -m venv backend/.venv

# 激活虚拟环境
source backend/.venv/bin/activate

# 安装依赖
pip install --upgrade pip
pip install -r backend/requirements.txt

# 启动应用（跳过虚拟环境创建）
./start_app.sh

验证 Python 版本

# 检查可用的 Python 版本
ls -la /opt/homebrew/bin/python* # macOS
ls -la /usr/bin/python*          # Linux

# 检查具体版本
python3 --version
python3.12 --version
python3.11 --version

# 检查虚拟环境使用的版本
backend/.venv/bin/python --version

其他常见 Python 问题

缺少编译工具

macOS:

# 安装 Xcode Command Line Tools
xcode-select --install

# 安装数学库
brew install openblas lapack

Linux:

# 安装编译工具
sudo apt install build-essential python3-dev

# 安装数学库
sudo apt install libopenblas-dev liblapack-dev

pip 安装太慢

使用国内镜像：

pip install -r backend/requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

或永久配置：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

权限问题

# 不要使用 sudo pip install
# 应该在虚拟环境中安装
source backend/.venv/bin/activate
pip install -r backend/requirements.txt

更新后的 start_app.sh 功能

新版脚本已自动：

1. ✅ 检测 Python 版本兼容性
2. ✅ 优先使用 Python 3.12 或 3.11
3. ✅ 警告不兼容的版本（3.13, 3.14）
4. ✅ 提供清晰的错误信息和解决方案
5. ✅ 自动重建不兼容的虚拟环境

再次运行 ./start_app.sh，脚本会：

• 检测到 Python 3.14 不兼容
• 自动查找 python3.12 或 python3.11
• 询问是否使用兼容版本
• 如果没有兼容版本，提供安装说明

推荐设置

在 ~/.zshrc 或 ~/.bashrc 中添加别名：

# 使用 Python 3.12 作为默认 python3
alias python3=python3.12
alias pip3=pip3.12

然后重新加载：

source ~/.zshrc  # or ~/.bashrc

---

问题2：LightGBM 编译失败

症状

× Failed to build installable wheels for some pyproject.toml based projects
╰─> lightgbm

原因

LightGBM 需要从源码编译，缺少编译依赖（cmake、libomp）。

解决方案

方案 1：安装编译依赖（推荐）

macOS:

# 安装编译工具
brew install cmake libomp

# 清理并重新安装
rm -rf backend/.venv
./start_app.sh

Linux:

# 安装编译工具
sudo apt update
sudo apt install cmake build-essential

# 清理并重新安装
rm -rf backend/.venv
./start_app.sh

方案 2：使用预编译的 wheel

# 激活虚拟环境
source backend/.venv/bin/activate

# 尝试安装预编译版本
pip install --only-binary :all: lightgbm

# 如果成功，更新 hash
md5 -q backend/requirements.txt > backend/.venv/.requirements.hash  # macOS
# 或
md5sum backend/requirements.txt | cut -d' ' -f1 > backend/.venv/.requirements.hash  # Linux

方案 3：不使用 LightGBM

如果上述方法都失败，可以暂时移除 LightGBM：

编辑 backend/requirements.txt，注释掉：

  scikit-learn==1.3.2
  xgboost==2.0.3
- lightgbm==4.1.0
+ # lightgbm==4.1.0  # Commented out due to build issues
  joblib==1.3.2

然后重新安装：

source backend/.venv/bin/activate
pip install -r backend/requirements.txt

注意：系统仍可正常运行，只是 ML 模型会少一个选项。

---

问题3：pydantic_settings 模块找不到

症状

ModuleNotFoundError: No module named 'pydantic_settings'

原因

依赖安装顺序问题，pydantic-settings 安装失败或被跳过。

解决方案

方案 1：使用更新的脚本（自动修复）

最新版 start_app.sh 已经修复了这个问题，采用分步安装策略：

# 删除旧虚拟环境
rm -rf backend/.venv

# 重新运行（会自动分步安装）
./start_app.sh

新脚本会：

1. 先安装 pydantic 和 pydantic-settings
2. 再安装其他依赖
3. 避免安装顺序冲突

方案 2：手动安装

# 激活虚拟环境
source backend/.venv/bin/activate

# 先安装核心依赖
pip install pydantic==2.5.0 pydantic-settings==2.1.0

# 再安装其他依赖
pip install -r backend/requirements.txt

# 验证安装
python -c "import pydantic_settings; print('OK')"

---

问题4：依赖安装太慢

症状

pip install 非常慢，特别是从 PyPI 下载。

解决方案

使用国内镜像源

临时使用：

source backend/.venv/bin/activate
pip install -r backend/requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

永久配置：

# 配置清华镜像
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 验证配置
pip config list

其他镜像源：

• 清华：https://pypi.tuna.tsinghua.edu.cn/simple
• 阿里云：https://mirrors.aliyun.com/pypi/simple
• 中科大：https://pypi.mirrors.ustc.edu.cn/simple
• 豆瓣：https://pypi.douban.com/simple

---

完整的故障排查流程

如果遇到任何安装问题，按以下步骤排查：

1. 检查 Python 版本

python3 --version
python3.12 --version  # 推荐使用这个

2. 检查编译工具

# macOS
xcode-select -p
brew list | grep -E "(cmake|libomp)"

# Linux
which gcc g++ make cmake

3. 清理环境重新安装

# 删除虚拟环境
rm -rf backend/.venv

# 删除 Python 缓存
find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
find . -type f -name "*.pyc" -delete

# 清空 pip 缓存
pip cache purge

# 重新安装
./start_app.sh

4. 查看详细错误日志

# 手动安装以查看完整错误
source backend/.venv/bin/activate
pip install -r backend/requirements.txt -v 2>&1 | tee install.log

# 查看日志
less install.log

5. 逐个安装问题包

source backend/.venv/bin/activate

# 分步安装
pip install numpy pandas  # 先安装基础包
pip install scikit-learn xgboost  # 再安装 ML 包
pip install lightgbm  # 最后安装可能有问题的包

---

快速修复命令

遇到问题？试试这个一键修复：

#!/bin/bash
# 清理并重装

echo "🧹 Cleaning up..."
rm -rf backend/.venv
find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true

echo "🔍 Checking Python..."
python3.12 --version || (echo "Please install Python 3.12: brew install [email protected]" && exit 1)

echo "🔧 Checking build tools..."
brew list cmake libomp || brew install cmake libomp

echo "🚀 Restarting..."
./start_app.sh

保存为 fix_install.sh 并运行：

chmod +x fix_install.sh
./fix_install.sh

---

获取帮助

如果以上方法都无法解决问题：

1. 查看完整错误日志并截图
2. 运行 python3 --version 和 pip list
3. 在 GitHub Issues 提交问题，附上：
   • 操作系统版本
   • Python 版本
   • 完整错误日志
   • pip list 输出

---

更新时间: 2025-11-15
脚本版本: start_app.sh v2.0